Webhooks

Manage webhook subscriptions and review event payload examples.

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

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://example.com/eventii/webhooks 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
OperationMethod and routeRequired scopeSuccessful response
List subscriptionsGET /webhooksWebhooks:Read200 OK
Create a subscriptionPOST /webhooksWebhooks:Create200 OK with the created subscription
Replace a subscriptionPUT /webhooks/{id}Webhooks:Update204 No Content
Delete a subscriptionDELETE /webhooks/{id}Webhooks:Delete204 No Content
List delivery logsGET /webhooks/{id}/logsWebhooks:Read200 OK
View an event previewGET /webhooks/event/{EventName}No additional Webhooks scope is declared200 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.id; 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.

FieldRequiredDescription
nameNoA label for your team.
eventNameYesOne supported event name from the catalogue.
uriInclude on create and updateThe destination URL.
authorizationTypeYesHeader, Query, Basic, or Bearer.
authorizationNameDependsRequired for Header, Query, and Basic.
authorizationValueDependsRequired 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.

authorizationTypeHow eventii sends itauthorizationNameauthorizationValue
HeaderA request headerHeader nameHeader value
QueryA URL query parameterParameter nameParameter value
BasicHTTP Basic authorizationUsernamePassword
BearerAuthorization: Bearer ...IgnoredToken

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 fieldMeaning
EventNameThe subscribed event type.
IdempotencyKeyA 32-character GUID without hyphens. Use it to recognize repeated delivery of the same payload.
CreatedAtUtcThe envelope creation time in UTC. For ordinary integration events, it is the event creation date.
DataThe 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 /webhooks/event/{EventName} returns a useful sample object for a supported event name. Its JSON is camel case and it is not the delivery contract.

ContextCasingIdentifier formatPurpose
Event previewcamel caseTypical GUIDs include hyphensExplore the API-reference sample.
Receiver deliveryPascalCaseIdempotencyKey is a 32-character GUID without hyphensProcess 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 nameSent whenKey identifiers in Data
TicketCreatedA ticket is created.TicketId, EventId, holder details, including HolderEmail, HolderPhone, and HolderType.
TicketActivatedA ticket is activated.TicketId, EventId, holder details, including HolderEmail, HolderPhone, and HolderType.
TicketUpdatedA ticket is updated.TicketId, HolderId, HolderExternalIds.
TicketForwardedA ticket is forwarded to a recipient.TicketId, Recipient.
TicketCancelledA ticket is cancelled.TicketId, HolderId, HolderExternalIds.
TicketReleasedA ticket is released.TicketId.
SeasonCardCreatedA season ticket is created.SeasonCardId, SeasonCardTypeId, HolderId, HolderEmail, HolderPhone.
SeasonCardActivatedA season ticket is activated.SeasonCardId, SeasonCardTypeId, HolderId, HolderEmail, HolderPhone.
SeasonCardUpdatedA season ticket is updated.SeasonCardId, HolderId, HolderExternalIds.
SeasonCardForwardedA season ticket is forwarded.SeasonCardId, HolderId, Recipient.
SeasonCardReleasedA season ticket is released for an event.SeasonCardId, EventId, HolderId.
SeasonCardCancelledA season ticket is cancelled.SeasonCardId, HolderId, HolderExternalIds.
OrderCreatedAn order is created.OrderId, customer and order-line identifiers.
OrderPaidAn order is paid.OrderId, transaction identifiers, order-line/item identifiers.
OrderCancelledAn order is cancelled.OrderId.
OrderLineCancelledAn order line is cancelled.OrderLineId.
CustomerCreatedA customer is created.CustomerId.
CustomerUpdatedA customer is updated.CustomerId.
CustomerDeletedA customer is deleted.CustomerId.
ConsentGrantedA customer consent is granted.CustomerId, ConsentTypeId.
ConsentRetractedA customer consent is retracted.CustomerId, ConsentTypeId.
PassEnteredA ticket or season ticket pass is used at an entrance.EntityId, EntranceId, EventId, HolderId.
PartnerRegistrationA partner registration is recorded.RegistrationId, PartnerId, RegistrationProductId, RegistrationOptionId, EventId.
TicketSubscriptionChangedA 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.

ChangeKindReceiver meaning
ActivatedThe subscription became active.
RenewedThe subscription was renewed.
PaymentFailedA 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.
CancelledThe subscription was cancelled.
UsedThe subscription was redeemed; it is not an admission event.
ReassignedOutOwnership moved away from this owner.
ReassignedInOwnership 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.ChangeKind and Data.Status.

{
  "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

SymptomLikely causeWhat to check
409 Conflict while creatingA subscription already exists for that event and API key.List subscriptions and update or delete the existing one.
400 Bad RequestA 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 UnauthorizedThe 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 403The receiver rejected delivery authentication.Verify the configured authorization type and its name/value semantics without exposing the value.
Receiver returns 404The destination path is wrong or no longer deployed.Update the full subscription with the correct absolute uri.
Receiver returns another non-2xx responseThe receiver could not accept the payload.Check delivery logs and receiver telemetry, then make the handler safely retryable.
No delivery appearsNo 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 fieldsA 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.