Every webhook request includes an HMAC-SHA256 signature in the X-Contro-Signature header. The signature format is t={timestamp},v1={hmac}, where the HMAC is computed over {timestamp}.{body}.
import crypto from "node:crypto";function verifyWebhookSignature(body, signatureHeader, secret) { const parts = Object.fromEntries( signatureHeader.split(",").map((p) => p.split("=", 2)) ); const timestamp = parts.t; const receivedHmac = parts.v1; const expected = crypto .createHmac("sha256", secret) .update(`${timestamp}.${body}`) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(receivedHmac), Buffer.from(expected) );}// In your webhook handler:app.post("/webhooks/contro", (req, res) => { const body = JSON.stringify(req.body); const signature = req.headers["x-contro-signature"]; if (!verifyWebhookSignature(body, signature, WEBHOOK_SECRET)) { return res.status(401).send("Invalid signature"); } // Process the event - event type is in the X-Contro-Event header const eventType = req.headers["x-contro-event"]; console.log("Event type:", eventType); res.status(200).send("OK");});
import hmacimport hashlibdef verify_webhook_signature(body: bytes, signature_header: str, secret: str) -> bool: parts = dict(p.split("=", 1) for p in signature_header.split(",")) timestamp = parts["t"] received_hmac = parts["v1"] expected = hmac.new( secret.encode(), f"{timestamp}.{body.decode()}".encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(received_hmac, expected)
Always verify webhook signatures before processing events. Unverified webhooks could be spoofed by attackers.
Retry policy
Failed deliveries (non-2xx responses or timeouts) are retried with exponential backoff:
Attempt
Delay
1st retry
1 minute
2nd retry
5 minutes
3rd retry
30 minutes
4th retry
2 hours
5th retry
24 hours
After 5 failed retries, the event is marked as failed. You can manually retry failed events.
Filter by delivery status. One of pending, delivered, failed.
eventType
string
Filter by event type. Example: "card.transaction".
from
string
ISO 8601 start timestamp (inclusive) on createdAt.
to
string
ISO 8601 end timestamp (inclusive) on createdAt.
Event fields
Field
Type
Description
id
string
Event ID. Example: "evt_abc123"
eventType
string
Event type. One of card.transaction, card.issued, card.status.changed, cardholder.kyc.updated, cardholder.created, balance.low, balance.top_up, kyc_session.completed, kyc_session.failed
status
string
Delivery status. One of pending, delivered, failed
attemptCount
number
Number of delivery attempts made. Example: 3
lastAttemptAt
string | null
ISO 8601 timestamp of last delivery attempt, or null. Example: "2026-03-20T14:30:00Z"
nextRetryAt
string | null
ISO 8601 timestamp of the next scheduled retry, or null if no retry is pending. Example: "2026-03-20T15:00:00Z"
lastResponseStatus
number | null
HTTP status code from the last delivery attempt, or null. Example: 500
createdAt
string
ISO 8601 event creation timestamp. Example: "2026-03-20T14:30:00Z"
Get a webhook event
Fetch a single delivery event including the full payload and the last response body. Both fields are redacted server-side to mask secrets, tokens, and other sensitive values.