Skip to main content

Webhook Best Practices

1. Respond Fast

Return 200 OK within 5 seconds. Process the event asynchronously after acknowledging:

2. Handle Duplicates

Use the event_id field (also sent as the X-Khaime-Event-Id header) for idempotency. The same event may be delivered more than once — retries reuse the same event_id:

3. Verify Before Processing

Always verify the signature using the raw request body before acting on a webhook. Reject unverified requests with 401.

4. Handle Missing Events

If a webhook is missed and you used the Sessions API, you can check the payment status directly:
For payments created via the Charge API, webhook delivery is the only confirmation mechanism. Ensure your webhook endpoint is reliable and returns 200 promptly.

5. Use the Envelope Fields

Every webhook includes useful envelope fields beyond the event data:
  • api_version — confirms which payload schema version was used
  • is_live — distinguish sandbox events from production
  • business_id — identify which merchant the event belongs to (useful in marketplace setups)

6. Log Everything

Log raw webhook payloads for debugging. Include the event_id, event_type, and processing result.

7. Use HTTPS

Webhook URLs must use HTTPS in production. Khaime will not deliver webhooks to HTTP endpoints in live mode.

8. Plan for New Event Types

New event types may be added without a version change. Your webhook handler should gracefully ignore unknown event_type values rather than erroring: