SeleID

Articles

Webhooks: signed events with retries and replay

SeleID webhooks deliver signed JSON events with retries, a delivery log and replay.

Published by SeleTech

Short answer

Webhooks tell your server when something happens. You register an HTTPS endpoint, choose the events you want, and we POST each event as JSON. Endpoint addresses must be HTTPS on a public hostname.

Every request is signed with your endpoint secret, which is shown once and can be rotated. The signature header carries a timestamp and an HMAC-SHA256 of the timestamp and raw body; you compare it in constant time and reject old timestamps. If your endpoint answers with an error, times out or is unreachable, delivery is retried with exponential backoff and, after the attempts run out, the delivery is marked failed and kept in a dead-letter list. Every attempt appears in a delivery log and you can replay an event. The same event can arrive more than once, so de-duplicate on the event id header. It is coming soon.

Frequently asked questions

How do I verify a webhook?

Compute HMAC-SHA256 over the timestamp and raw body with your endpoint secret, compare it in constant time and reject old timestamps.

Can the same event arrive twice?

Yes. De-duplicate on the event id header.

What if my server is down?

Deliveries are retried with backoff, then kept in a dead-letter list you can replay from.

Related