Webhooks
When an event occurs, a webhook subscription sends a POST request to its configured URL. With an API key, you can list subscriptions and create one for each event type. You can also update or delete a subscription and inspect its delivery logs.
Contents
- When to use webhooks
- Before you start
- Create a subscription
- Manage subscriptions
- Delivery request
- Event catalogue
- Build a reliable receiver
- Inspect previews and delivery logs
- Troubleshooting
When to use webhooks
Webhooks notify your system that something changed in eventii. They are useful for reacting to ticket, season-ticket, order, customer, consent, access, and partner-registration activity without polling for every change.
Use the REST API to read current state. A delivery tells your integration to process or reconcile a change, but it may not contain the complete current resource. Read that resource when a later change may have followed the event, the delivery may be a duplicate, or your receiver was unavailable.
These webhooks belong to the eventii Open API and are managed with your API key. Access is a separate admission platform with its own signed PassEntered webhook. eventii sets it up during Access onboarding, not through this API. See Access ticketing provider integration. The event names and payloads described here do not apply to Access.
Each subscription listens for one event name and sends to one URL. An API key can have only one subscription for a given event; creating a second one for the same event returns 409 Conflict. Subscriptions belong to the API key and tenant context, so use the same key to create, list, update, inspect, and delete them.
Use a separate API key for each environment, such as staging and production. With one shared key, staging and production cannot both subscribe to the same event, and a change made while testing would affect your production deliveries. Contact eventii for an extra key.
Before you start
You need an eventii Open API key with the Webhooks scope required for each management operation. Keep the key on the system that manages subscriptions. It is separate from the credential eventii sends to your receiver.
Your receiver needs a publicly reachable HTTPS URL that accepts an HTTP POST and JSON. Use a neutral test endpoint such as https:/ only as a placeholder; replace it with your own endpoint before creating a subscription.
Choose receiver authentication before subscribing. eventii can add one static credential to each delivery, but it does not send an HMAC signature. Protect the receiver URL and configured authorization values in your deployment and observability systems.
API endpoints and scopes
All management requests use the X-API-KEY request header and the version-1 base URL:
https://openapi.eventii.dk/v1
| Operation | Method and route | Required scope | Successful response |
|---|---|---|---|
| List subscriptions | GET / | Webhooks:Read | 200 OK |
| Create a subscription | POST / | Webhooks:Create | 200 OK with the created subscription |
| Replace a subscription | PUT / | Webhooks:Update | 204 No Content |
| Delete a subscription | DELETE / | Webhooks:Delete | 204 No Content |
| List delivery logs | GET / | Webhooks:Read | 200 OK |
| View an event preview | GET / | No additional Webhooks scope is declared | 200 OK |
The preview endpoint is an API-reference aid. It does not create a subscription and does not send a test delivery.
Create a subscription
Create one subscription for one event and receiver endpoint. The request uses uri, not url.
curl --request POST "https://openapi.eventii.dk/v1/webhooks" \
--header "X-API-KEY: $EVENTII_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Ticket-created receiver",
"eventName": "TicketCreated",
"uri": "https://example.com/eventii/webhooks",
"authorizationType": "Header",
"authorizationName": "X-Webhook-Token",
"authorizationValue": "replace-with-a-receiver-secret"
}'
The request returns 200 OK when successful. Save result.; use it to update or delete the subscription and inspect its logs.
{
"result": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Ticket-created receiver",
"eventName": "TicketCreated",
"url": "https://example.com/eventii/webhooks"
}
}
The following request fields are accepted when creating or updating a subscription.
| Field | Required | Description |
|---|---|---|
name | No | A label for your team. |
eventName | Yes | One supported event name from the catalogue. |
uri | Include on create and update | The destination URL. |
authorizationType | Yes | Header, Query, Basic, or Bearer. |
authorizationName | Depends | Required for Header, Query, and Basic. |
authorizationValue | Depends | Required for Header, Query, Basic, and Bearer. |
Although None exists in the underlying authorization enum, the public create and update validators require a non-empty authorization type. Configure one of the four supported credential forms above.
Receiver authentication
Use X-API-KEY to call the eventii management API. eventii does not send that key to your receiver. Set the delivery credential separately in the subscription.
authorizationType | How eventii sends it | authorizationName | authorizationValue |
|---|---|---|---|
Header | A request header | Header name | Header value |
Query | A URL query parameter | Parameter name | Parameter value |
Basic | HTTP Basic authorization | Username | Password |
Bearer | Authorization: Bearer . | Ignored | Token |
For Header, use a receiver-specific header name, such as X-Webhook-Token. For Bearer, provide only the token value, not the Bearer prefix. Do not put a real key, token, password, or receiver URL containing credentials in source control, documentation, or logs.
Manage subscriptions
List the subscriptions accessible to the API key before creating more. This also lets you find the subscription ID for management operations.
curl --request GET "https://openapi.eventii.dk/v1/webhooks" \
--header "X-API-KEY: $EVENTII_API_KEY"
Update replaces the subscription configuration. Send the full subscription request body, including its event name, URI, and authentication fields. The endpoint is PUT. There is no partial-update (PATCH) endpoint.
curl --request PUT "https://openapi.eventii.dk/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
--header "X-API-KEY: $EVENTII_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"name": "Ticket-created receiver",
"eventName": "TicketCreated",
"uri": "https://example.com/eventii/webhooks",
"authorizationType": "Bearer",
"authorizationValue": "replace-with-a-receiver-token"
}'
To remove a subscription, delete it by ID. Deleting a subscription stops future deliveries for that subscription.
curl --request DELETE "https://openapi.eventii.dk/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
--header "X-API-KEY: $EVENTII_API_KEY"
The public management API has no enable/disable toggle or replay endpoint. To recover a missed business update, first inspect the delivery logs, then use the REST API to reconcile current state.
Delivery request
eventii delivers JSON by POST to the configured uri. The delivery envelope uses PascalCase field names.
{
"EventName": "TicketCreated",
"IdempotencyKey": "b7d7cfc80de04a09bdb630847ce48773",
"CreatedAtUtc": "2026-09-17T10:00:00Z",
"Data": {
"Id": "b7d7cfc8-0de0-4a09-bdb6-30847ce48773",
"CreationDate": "2026-09-17T10:00:00Z",
"TenantId": "06837dd7-13c1-4dc8-94f8-fb555ad8d913",
"OrganiserId": "06837dd7-13c1-4dc8-94f8-fb555ad8d913",
"TicketId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"Barcode": "1234567890123456",
"TicketStatus": "Active",
"EventId": "7ca7a8a9-d4fd-4eea-9ee0-d0f143628a3f",
"EventName": "Example event",
"EventTime": "2026-09-20T14:00:00Z",
"HolderEmail": "holder@example.com",
"HolderPhone": "+4512345678",
"HolderType": "B2C"
}
}
This TicketCreated payload is an example; other event types include different fields. The API reference preview is only a supplementary example. Parse deliveries according to the delivery contract because previews do not show the complete delivery schema.
| Envelope field | Meaning |
|---|---|
EventName | The subscribed event type. |
IdempotencyKey | A 32-character GUID without hyphens. Use it to recognize repeated delivery of the same payload. |
CreatedAtUtc | The envelope creation time in UTC. For ordinary integration events, it is the event creation date. |
Data | The event-specific object. |
For most integration events, Data also carries Id, CreationDate, TenantId, and OrganiserId. TicketForwarded is intentionally smaller and contains only TicketId and Recipient. TicketReleased contains only TicketId. Both projected payloads use an envelope timestamp assigned when eventii publishes the delivery, rather than the source event's CreationDate.
Preview JSON versus delivery JSON
GET / returns a useful sample object for a supported event name. Its JSON is camel case and it is not the delivery contract.
| Context | Casing | Identifier format | Purpose |
|---|---|---|---|
| Event preview | camel case | Typical GUIDs include hyphens | Explore the API-reference sample. |
| Receiver delivery | PascalCase | IdempotencyKey is a 32-character GUID without hyphens | Process a real event. |
For example, a preview can contain eventTimeUtc, while a real TicketCreated delivery uses EventTime. The TicketForwarded preview exposes its source model's holder fields, but the delivery projects Data to only TicketId and Recipient. The TicketReleased preview contains TicketId, while its delivery adds the PascalCase envelope and a publication-time CreatedAtUtc. Build your receiver against the delivery contract; use previews only as supplementary examples.
Event catalogue
The supported event names are exact and case-sensitive. There are 24 public event names.
| Event name | Sent when | Key identifiers in Data |
|---|---|---|
TicketCreated | A ticket is created. | TicketId, EventId, holder details, including HolderEmail, HolderPhone, and HolderType. |
TicketActivated | A ticket is activated. | TicketId, EventId, holder details, including HolderEmail, HolderPhone, and HolderType. |
TicketUpdated | A ticket is updated. | TicketId, HolderId, HolderExternalIds. |
TicketForwarded | A ticket is forwarded to a recipient. | TicketId, Recipient. |
TicketCancelled | A ticket is cancelled. | TicketId, HolderId, HolderExternalIds. |
TicketReleased | A ticket is released. | TicketId. |
SeasonCardCreated | A season ticket is created. | SeasonCardId, SeasonCardTypeId, HolderId, HolderEmail, HolderPhone. |
SeasonCardActivated | A season ticket is activated. | SeasonCardId, SeasonCardTypeId, HolderId, HolderEmail, HolderPhone. |
SeasonCardUpdated | A season ticket is updated. | SeasonCardId, HolderId, HolderExternalIds. |
SeasonCardForwarded | A season ticket is forwarded. | SeasonCardId, HolderId, Recipient. |
SeasonCardReleased | A season ticket is released for an event. | SeasonCardId, EventId, HolderId. |
SeasonCardCancelled | A season ticket is cancelled. | SeasonCardId, HolderId, HolderExternalIds. |
OrderCreated | An order is created. | OrderId, customer and order-line identifiers. |
OrderPaid | An order is paid. | OrderId, transaction identifiers, order-line/item identifiers. |
OrderCancelled | An order is cancelled. | OrderId. |
OrderLineCancelled | An order line is cancelled. | OrderLineId. |
CustomerCreated | A customer is created. | CustomerId. |
CustomerUpdated | A customer is updated. | CustomerId. |
CustomerDeleted | A customer is deleted. | CustomerId. |
ConsentGranted | A customer consent is granted. | CustomerId, ConsentTypeId. |
ConsentRetracted | A customer consent is retracted. | CustomerId, ConsentTypeId. |
PassEntered | A ticket or season ticket pass is used at an entrance. | EntityId, EntranceId, EventId, HolderId. |
PartnerRegistration | A partner registration is recorded. | RegistrationId, PartnerId, RegistrationProductId, RegistrationOptionId, EventId. |
TicketSubscriptionChanged | A ticket subscription changes through an accepted lifecycle transition. | TicketSubscriptionId, TicketSubscriptionVersion, ChangeKind, owner, card, price, status, and optional used-event identifiers. Used is redemption, not admission. |
TicketSubscriptionChanged is delivered for Activated, Renewed, PaymentFailed, Cancelled, Used, ReassignedOut, and ReassignedIn. Its Data includes the standard Id, CreationDate, TenantId, and OrganiserId metadata, but excludes upstream marketing fields such as e-mail, related e-mails, holder name, run ID, and contract version.
ChangeKind | Receiver meaning |
|---|---|
Activated | The subscription became active. |
Renewed | The subscription was renewed. |
PaymentFailed | A renewal payment for an existing subscription was confirmed declined. It is not emitted for pending or timed-out payments, or for an initial payment that never activated a subscription. |
Cancelled | The subscription was cancelled. |
Used | The subscription was redeemed; it is not an admission event. |
ReassignedOut | Ownership moved away from this owner. |
ReassignedIn | Ownership moved to this owner. |
The CTS producer emits this event only when it can resolve an owner and e-mail. Webhooks forwards the approved public projection and does not resolve either field. Internal Snapshot, Unknown, and unrecognized change kinds are suppressed before subscriptions are queried. Used means subscription redemption, not admission. Status is Expired for PaymentFailed. During recovery, a Renewed event can still have Expired status; read the current resource if your receiver needs the latest state.
There is no standalone ticket-subscription-created, payment-failed, or expired webhook event. Subscribe to TicketSubscriptionChanged and inspect Data. and Data..
{
"EventName": "TicketSubscriptionChanged",
"IdempotencyKey": "b7d7cfc80de04a09bdb630847ce48773",
"CreatedAtUtc": "2026-09-17T10:00:00Z",
"Data": {
"Id": "b7d7cfc8-0de0-4a09-bdb6-30847ce48773",
"CreationDate": "2026-09-17T10:00:00Z",
"TenantId": "06837dd7-13c1-4dc8-94f8-fb555ad8d913",
"OrganiserId": "06837dd7-13c1-4dc8-94f8-fb555ad8d913",
"TicketSubscriptionVersion": 42,
"ChangeKind": "Activated",
"TicketSubscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"CustomerId": "4fa85f64-5717-4562-b3fc-2c963f66afa6",
"OwnerType": "Customer",
"OwnerId": "4fa85f64-5717-4562-b3fc-2c963f66afa6",
"CardTypeId": "5fa85f64-5717-4562-b3fc-2c963f66afa6",
"CardTypeName": "Season ticket",
"PriceCategoryId": "6fa85f64-5717-4562-b3fc-2c963f66afa6",
"PriceCategoryName": "Adult",
"Status": "Active",
"ExpirationUtc": "2027-06-01T00:00:00Z",
"UsedEventId": null,
"UsedEventName": null,
"UsedEventStartUtc": null
}
}
An actual declined-payment delivery uses the PascalCase delivery contract. The preview endpoint remains a generic camel-case Activated sample and does not select this example.
{
"EventName": "TicketSubscriptionChanged",
"IdempotencyKey": "c7d7cfc80de04a09bdb630847ce48774",
"CreatedAtUtc": "2026-09-21T10:00:00Z",
"Data": {
"Id": "c7d7cfc8-0de0-4a09-bdb6-30847ce48774",
"CreationDate": "2026-09-21T10:00:00Z",
"TenantId": "06837dd7-13c1-4dc8-94f8-fb555ad8d913",
"OrganiserId": "06837dd7-13c1-4dc8-94f8-fb555ad8d913",
"TicketSubscriptionVersion": 43,
"ChangeKind": "PaymentFailed",
"TicketSubscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"Status": "Expired"
}
}
Build a reliable receiver
Return an HTTP 2xx response only after your receiver has durably accepted the delivery. Record the idempotency key with the business work in one durable transaction or inbox. If you have already processed the key, acknowledge the duplicate with 2xx without repeating the business action.
Your receiver must tolerate duplicate deliveries and out-of-order events. Do not assume exactly-once delivery or a particular order. If an update conflicts with local state, read the relevant eventii REST resource and reconcile from it.
Treat non-2xx responses as failed attempts and keep enough receiver telemetry to diagnose them. The public contract does not specify a retry count, schedule, window, or replay capability. Do not make business correctness depend on a particular retry policy.
Keep the HTTP handling path short. Store the accepted payload and schedule slower work separately when appropriate. If you cannot safely persist it, return a non-success response and investigate through logs and REST reconciliation.
Inspect previews and delivery logs
Preview the shape of one supported event before implementing its handler:
curl --request GET "https://openapi.eventii.dk/v1/webhooks/event/TicketCreated" \
--header "X-API-KEY: $EVENTII_API_KEY"
Inspect a subscription's delivery history with the subscription ID:
curl --request GET "https://openapi.eventii.dk/v1/webhooks/3fa85f64-5717-4562-b3fc-2c963f66afa6/logs" \
--header "X-API-KEY: $EVENTII_API_KEY"
Logs are newest first. Each entry records the subscription and event, destination URL, authorization type, delivered payload (dataObject), response code and content, and timestamp. dataObject is a JSON-encoded string. Results are cached for two minutes, so a recent delivery may not appear immediately. Keep authorization details, receiver response bodies, and personal data out of tickets and public support requests.
Use a log entry to correlate the destination and outcome with your receiver's own request tracing. If an event appears absent, inspect the subscription configuration and logs first, then reconcile the resource through REST rather than expecting a replay endpoint.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
409 Conflict while creating | A subscription already exists for that event and API key. | List subscriptions and update or delete the existing one. |
400 Bad Request | A required field, absolute uri, authorization field, or event name is invalid. | Check the request fields and use an event name from the catalogue exactly. |
401 Unauthorized | The API key is missing, invalid, or lacks the required scope. | Send X-API-KEY and confirm the operation's Webhooks scope. |
Receiver returns 401 or 403 | The receiver rejected delivery authentication. | Verify the configured authorization type and its name/value semantics without exposing the value. |
Receiver returns 404 | The destination path is wrong or no longer deployed. | Update the full subscription with the correct absolute uri. |
Receiver returns another non-2xx response | The receiver could not accept the payload. | Check delivery logs and receiver telemetry, then make the handler safely retryable. |
| No delivery appears | No matching subscription exists, the wrong event name was selected, or the event did not occur in the API key/tenant context. | List subscriptions, verify the exact event name, and reconcile through REST. |
| Preview fields do not match receiver fields | A preview is camel case while delivery uses PascalCase; some event models differ. | Build against the delivery envelope and use the preview only as a schema aid. |
If the configuration, receiver, and logs do not explain the result, retain the subscription ID, event name, approximate UTC timestamp, and response status for support. Do not include API keys, authorization values, or unredacted payloads.