Set up webhooks

Use this to notify an external system when something happens in ToucanTix, for example when an order settles or a customer changes newsletter consent. Webhooks push signed JSON events to an HTTPS URL you control.

Integration settings and connection status in the back office — Use the integrations area to verify credentials, connection state, and external-system setup.

Before you start

Confirm:

you have an HTTPS endpoint that can receive POST requests and respond quickly
you have back-office permission to manage webhook endpoints under Admin > Webhooks
you know which event types the receiving system needs

Create a webhook endpoint

In the back office, open Admin > Webhooks.
On the Webhook endpoints page, select Create.
Enter the Endpoint URL. It must be a valid HTTPS URL.
Select the Event types that should trigger this webhook.
Optionally select a Point of sale to filter events for one point of sale. A point of sale is required when you select booking events.
Leave Active selected; inactive webhooks do not receive events.
Select Create webhook.
Copy the secret from the Webhook secret dialog and store it securely.

Available event types

Select from these event types when creating or editing an endpoint:

Orders: Order Settled
Bookings: Booking Created, Booking Updated, Booking Cancelled, Quota Updated
Customers: Contact Created, Contact Updated, Contact Deleted, Contact Newsletter Consent Changed, Contact Subscription Added, Contact Subscription Removed
Segments: Segment Created, Segment Updated, Segment Deleted, Segment Membership Added

Verify deliveries

Each delivery is a JSON POST that includes the event ID, event type, and the affected resource. The Webhook contract section on the webhooks page shows a sample payload and the headers:

`X-Toucantix-Webhook-Signature` — HMAC-SHA256 over `timestamp.payload` using the endpoint secret, formatted as `t=<timestamp>,v1=<hex>`
`X-Webhook-Event-Id` — the stable event ID to use for deduplication
`X-Webhook-Event-Type` — the event key for this delivery
`X-Webhook-Timestamp` — the Unix timestamp used in signature verification

Verify the signature on the raw request body for every delivery. Compare the expected and received HMAC with a constant-time comparison, and reject timestamps more than five minutes from your receiver's current time. Store `X-Webhook-Event-Id` with the processing result and make handling idempotent: a repeated event ID must be rejected or acknowledged without applying the event twice. This protects against both replayed requests and normal delivery retries.

To test the wiring, open the endpoint's edit page and select Send test event; ToucanTix queues a sample event to your URL.

Delivery, retries, and monitoring

Failed deliveries are retried with delays of 30 seconds, 60 seconds, 5 minutes, 15 minutes, and then 30 minutes. When retries are exhausted, the delivery is marked dead-lettered and is not retried again.

The Webhook endpoints list shows Last delivery, Failures, and a Status of Healthy, Failing, or Disabled per endpoint, so you can spot a broken receiver quickly.

To stop deliveries permanently, archive the endpoint; archiving stops all deliveries to that URL and can be undone from the archived list.

Expected result

Your endpoint receives signed JSON events for the selected event types shortly after they happen, a test event arrives on demand, and the endpoint shows Healthy in the list.

Troubleshooting

Problem	What to check
No events arrive	The endpoint is Active, not archived, the right Event types are selected, and no Point of sale filter excludes the events.
Endpoint shows Failing	Your receiver returns a success status quickly; check Last delivery and Failures in the list and your server logs.
Signature verification fails	You verify HMAC-SHA256 over `timestamp.payload` with the stored secret; if the secret is lost, create a new endpoint.
Events stop after repeated failures	Dead-lettered deliveries are not retried; fix the receiver and use Send test event to confirm recovery.