POST with an event to your endpoint whenever
something happens. Events have the same shape regardless of the payment provider.
Register an endpoint
enabled_events, or all events with ["*"] (default).
Verify the signature
Each delivery has aKalixo-Signature header:
v1 is the hex HMAC-SHA256 of "<t>.<raw request body>" with your endpoint secret.
Reject the request if no v1 matches or if t is more than 5 minutes old.
Delivery rules
- Answer with any
2xxwithin 10 seconds, then process asynchronously. - Delivery is at least once. Deduplicate on the event
id. - Order is not guaranteed. Every event contains the full object with a
versionthat increases with every change; ignore events with a lowerversionthan you already stored. - Failed deliveries are retried with exponential backoff for about 3 days (1 minute, 5 minutes, 30 minutes, 2 hours, … 24 hours). Redirects are not followed.
- Missed something? List events with
GET /v1/events(kept for 30 days) or read the object directly.
Secret rotation
POST /v1/webhook-endpoints/{id}/rotate-secret returns a new secret. For 24 hours Kalixo
signs every delivery with both secrets (two v1 values), so you can deploy the new secret without downtime.