Webhook delivery and troubleshooting

Idempotency

Events may be delivered more than once. Use the webhook-id request header to deduplicate: store the IDs you have processed and reject repeats. webhook-id is generated by Alianza and is stable across retries of the same event.

Response codes and retries

Return HTTP 200–299 to acknowledge an event. Any other response — including timeouts — triggers a retry.

Keep your endpoint fast: acknowledge receipt, then process asynchronously. Aim to respond well within 15 seconds.

Spec gap. A 15-second endpoint timeout is recommended, but the retry schedule — attempt count, backoff strategy, and the point at which an event is dropped — is not documented. Confirm delivery guarantees with Alianza before building alerting on missed events.

Gap ID webhook-timeout

Troubleshooting

Events are not arriving at all

  • Verify your event subscription was created successfully by the Alianza team.
  • Confirm your endpoint is reachable from the internet (not localhost).
  • Ask Alianza to check delivery logs for attempted calls.

The same event arrives more than once

This is expected, not a fault. Delivery is at-least-once, so deduplicate on webhook-id as described above.

Some events are missing

  • Check your endpoint's response codes. Non-2xx responses trigger retries, but persistent failures may exhaust them.
  • Verify your endpoint does not time out under load. The recommended budget is 15 seconds.

Security

Spec gap. There is no way to authenticate an incoming event yet. Payload signature verification is not available; a future version will add HMAC verification via a webhook-signature header. Until it ships, treat every payload as unauthenticated input: anyone who learns your destination URL can post to it, so validate the body against your own schema, and re-read state through the API before acting on anything that matters. Ask your Alianza contact what interim controls are available for your deployment rather than assuming any are in place.

Gap ID webhook-signature

Support and next steps

While the Experience Provider programme is in early access, issues and questions go to Alianza Engineering through the channel set up for your integration — normally your Alianza point of contact, by email or shared Slack channel. A dedicated support intake for Experience Providers is planned; this page will change when it exists.

Future versions will add HMAC signature verification and advanced event filtering.