Skip to main content
Kalixo sends an HTTP POST with an event to your endpoint whenever something happens. Events have the same shape regardless of the payment provider.

Register an endpoint

Subscribe to specific types with enabled_events, or all events with ["*"] (default).

Verify the signature

Each delivery has a Kalixo-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.
Verify against the raw body. Parsing and re-serializing JSON changes the bytes.

Delivery rules

  • Answer with any 2xx within 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 version that increases with every change; ignore events with a lower version than 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.