Webhooks / Verifying signatures

Verifying webhook signatures

Every webhook kepa sends is signed with HMAC-SHA256. Verify the signature on every request — it's the only way to confirm the event came from us and hasn't been tampered with.

IMPORTANTWithout verification, anyone who learns your endpoint URL can post events. Settlements, refunds, and disputes all flow through webhooks — treat the signing secret like a key.

The signature header

Every webhook carries an X-Kepa-Signature header with a timestamp and a signature, alongside X-Kepa-Event-ID and X-Kepa-Delivery-ID for logging and deduplication.

X-Kepa-Signature: t=1712668094,v1=5257a869e7ecebed...

Steps

Extract the timestamp and the v1 signature from the header.
Concatenate {timestamp}.{raw_body}.
Compute HMAC-SHA256 of the concatenated string using your endpoint's signing secret.
Compare with constant-time equality. Reject if they differ, or the timestamp is older than 5 minutes.

Event types

payment.capturedA sale or capture was approved and captured.

payment.refundedA refund cleared the acquirer.

payment_intent.succeededAn online payment completed.

payment_intent.declinedAn online payment was declined.

checkout_session.completedA hosted checkout session finished successfully.

payment_method.attachedA card was saved to a customer.

dispute.createdA chargeback was raised.

payout.paidA payout was paid to the merchant's bank account.

import { verifySignature } from "@kepa/sdk"; app.post("/webhook", (req, res) => { const ok = verifySignature({ payload: req.rawBody, header: req.headers["x-kepa-signature"], secret: process.env.KEPA_WH_SECRET, }); if (!ok) return res.status(401).end(); const event = JSON.parse(req.rawBody); switch (event.eventType) { case "payment.captured": handle(event.data); break; // ... } res.status(200).end(); });

{ "id": "evt_3a4b8c2d", "deliveryId": "whd_01HX9KP3", "eventType": "payment.captured", "createdAt": "2026-04-09T21:08:14Z", "data": { "id": "txn_01HX9KP3RKZ7Q2", "amount": 4250, "currency": "NZD", "authorizationCode": "A91823" } }