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 includes a Kepa-Signature header containing a timestamp and one or more signatures.

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

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.succeededA sale reached approved.

payment.failedA sale reached declined or error.

refund.succeededA refund cleared the acquirer.

dispute.openedA chargeback was raised.

settlement.paidA daily batch was paid to the bank.

terminal.onlineA previously offline device reconnected.

terminal.offlineA device has missed 3+ heartbeats.

firmware.updatedA device successfully upgraded firmware.

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

{ "id": "evt_3a4b8c2d", "event": "payment.succeeded", "created": "2026-04-09T21:08:14Z", "livemode": true, "data": { "id": "txn_01HX9KP3RKZ7Q2", "amount": 4250, "currency": "NZD", "auth_code": "A91823" } }