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.

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

Events are not authenticated. Signature verification is not available yet, so anyone who learns your destination URL can post to it. Treat every payload as untrusted input: validate it 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.

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.