Webhooks

Webhooks let you receive HTTP callbacks when events occur in your partner account - such as card transactions, KYC status changes, or balance updates.

Configure webhooks

Get current config

curl https://api.contro.me/v1/partner/webhooks/config \
  -H "x-contro-api-key: $CONTRO_API_KEY"

const config = await contro.webhooks.getConfig();

config = contro.webhooks.get_config()

Response:

{
  "webhookUrl": "https://your-app.com/webhooks/contro",
  "webhookSecret": "whsec_...",
  "subscribedEvents": ["card.transaction", "cardholder.kyc.updated"]
}

Update config

curl -X PATCH https://api.contro.me/v1/partner/webhooks/config \
  -H "x-contro-api-key: $CONTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-app.com/webhooks/contro",
    "webhookSecret": "whsec_your_secret_min_16_chars",
    "subscribedEvents": ["card.transaction", "cardholder.kyc.updated", "balance.low"]
  }'

await contro.webhooks.updateConfig({
  webhookUrl: "https://your-app.com/webhooks/contro",
  webhookSecret: "whsec_your_secret_min_16_chars",
  subscribedEvents: ["card.transaction", "cardholder.kyc.updated", "balance.low"],
});

contro.webhooks.update_config(
    webhook_url="https://your-app.com/webhooks/contro",
    webhook_secret="whsec_your_secret_min_16_chars",
    subscribed_events=["card.transaction", "cardholder.kyc.updated", "balance.low"],
)

Field	Type	Description
`webhookUrl`	string	HTTPS URL to receive events. Must use `https://`. Example: `"https://your-app.com/webhooks/contro"`
`webhookSecret`	string	Secret for HMAC-SHA256 signature verification. Min 16 characters. Example: `"whsec_your_secret_min_16_chars"`
`subscribedEvents`	string[]	Event types to subscribe to. Example: `["card.transaction", "cardholder.kyc.updated"]`

Event types

Event	Description
`card.transaction`	Card transaction lifecycle event (authorized, settled, declined, reversed)
`card.issued`	A new card was issued
`card.status.changed`	A card was activated, frozen, unfrozen, or cancelled
`card.3ds_otp`	3DS one-time passcode for partner-issued cards — deliver to cardholder within 60s
`cardholder.kyc.updated`	KYC status changed (approved, rejected)
`cardholder.approved`	Cardholder passed KYC and can be issued cards
`cardholder.created`	A new cardholder was created
`balance.low`	Balance fell below threshold (daily check)
`balance.alert`	Balance crossed the alert threshold (fires immediately, once per crossing)
`balance.top_up`	Balance was topped up
`kyc_session.completed`	A KYC session was approved
`kyc_session.failed`	A KYC session was rejected

Verifying webhook signatures

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 hmac
import hashlib

def 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.

List webhook events

View the delivery history for your webhooks:

curl "https://api.contro.me/v1/partner/webhooks/events?limit=20&status=failed" \
  -H "x-contro-api-key: $CONTRO_API_KEY"

const events = await contro.webhooks.listEvents({
  limit: 20,
  status: "failed",
});

events = contro.webhooks.list_events(limit=20, status="failed")

Query parameters

Parameter	Type	Description
`page`	integer	Page number (default `1`).
`limit`	integer	Items per page (1–100, default `20`). Example: `50`
`status`	string	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.

curl https://api.contro.me/v1/partner/webhooks/events/{eventId} \
  -H "x-contro-api-key: $CONTRO_API_KEY"

const event = await contro.webhooks.getEvent("evt_abc123");

event = contro.webhooks.get_event("evt_abc123")

Additional response fields

In addition to the list fields above, the detail response includes:

Field	Type	Description
`payload`	string	Redacted JSON body that was (or will be) sent to your endpoint.
`lastResponseBody`	string \| null	Redacted response body from the destination, or `null`.
`webhookUrl`	string \| null	Destination URL the event was delivered to, or `null` if not configured.

Retry a failed event

Manually retry delivery of a failed event:

curl -X POST https://api.contro.me/v1/partner/webhooks/events/{eventId}/retry \
  -H "x-contro-api-key: $CONTRO_API_KEY"

await contro.webhooks.retryEvent("evt_abc123");

contro.webhooks.retry_event("evt_abc123")

Getting started

Core resources

Platform

Configure webhooks

Get current config

Update config

Event types

Verifying webhook signatures

Retry policy

List webhook events

Query parameters

Event fields

Get a webhook event

Additional response fields

Retry a failed event

​Configure webhooks

​Get current config

​Update config

​Event types

​Verifying webhook signatures

​Retry policy

​List webhook events

​Query parameters

​Event fields

​Get a webhook event

​Additional response fields

​Retry a failed event

Configure webhooks

Get current config

Update config

Event types

Verifying webhook signatures

Retry policy

List webhook events

Query parameters

Event fields

Get a webhook event

Additional response fields

Retry a failed event