Set up webhooks

Use this to notify an external system when something happens in KORONA Event, 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

Using Order Settled for external analytics

Order Settled is an authoritative server-side notification that an order entered a settled payment state. Its payload includes the order number, payment state and method, currency, total and settled gross values, and settled line items.

It is not a ready-made Google Ads or GA4 conversion feed. The webhook does not contain browser campaign parameters or click identifiers such as gclid, fbclid, or UTM values. It also does not provide the per-item net prices or tax rates needed to reconstruct mixed-tax GA4 item values. A server-side advertising integration must obtain the legally permitted click or session identifier and any required tax-exclusive commerce data separately, join them to the settled order, deduplicate webhook deliveries, and send the destination request itself.

For browser-side campaign attribution and purchase events, use Configure external analytics and consent.

Booking identity for grouped event templates

For offerable.booking.created, offerable.booking.updated, and offerable.booking.cancelled, the offerable_* fields identify the public offer that an external system can query or book. When an occurrence was created from an internal child event template in a group, these fields therefore identify the public parent event template rather than the internal child.

Field	Grouped event-template booking
`offerable_id`	ID of the public parent event template
`offerable_name`	Name of the public parent event template
`offerable_type`	`EVENT_TEMPLATE`
`on_demand_event_id`	ID of the materialized occurrence
`offerable_span`, `offerable_span_begin`, `offerable_span_end`	Time span of that occurrence

KORONA Event still calculates the quota and point-of-sale routing from the internal source template and the specific occurrence. It retains the child ID as source_event_template_id in the integration-event metadata for routing and diagnostics; this internal metadata is not an additional field in the delivered JSON body. Ungrouped event templates use their own ID in both roles.

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; KORONA Event 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.