Kushki Webhooks: how to process payment events without missing a single one
Webhooks are the source of truth for your transactions. We show you how to verify HMAC signatures, handle retries, and guarantee exactly-once delivery.
March 25, 2026
·11 minIf your integration updates payment status based on the checkout response, you have a production bug waiting to happen. The checkout response can be lost due to a closed browser, network timeout or client error. Webhooks are the only reliable source of truth.
Webhook event structure
Kushki sends a signed HTTPS POST to your endpoint with a JSON payload. The event field indicates the event type (payment.succeeded, payment.failed, refund.created, etc.) and the data field contains the complete transaction object.
HMAC signature verification
Each request includes the X-Kushki-Signature header with an HMAC-SHA256 signature of the body. Always verify the signature before processing the event — this prevents malicious actors from calling your endpoint with fake data.
Never process a webhook without verifying the signature. Even if your endpoint isn't publicly exposed, always validate the authenticity of the origin.
Idempotency: the same event can arrive twice
Kushki retries a webhook if your endpoint doesn't respond with HTTP 200 within 5 seconds. This means the same event can arrive multiple times. Save the event.id in your database and verify if it's already been processed before executing any business logic.