Webhooks

Signed notifications (Clobepay-Signature) with retries, secret rotation and resend.

Clobepay notifies you over HTTPS when the status of a payin, payout or verification of your merchant changes. Each notification is signed with your endpoint’s secret.

Webhook delivery
  • pending → in_flight: HTTPS to your URL
  • pending → abandoned: Endpoint disabled
  • in_flight → succeeded: 2xx
  • in_flight → pending: Error or timeout (retry)
  • in_flight → failed: No more retries

Registering the endpoint

  • From the dashboard (Integration settings) or via API with POST /webhook-endpoints.
  • Only https:// on port 443, with no user or password in the URL and no redirects.
  • Private or internal addresses are not allowed: the API returns 422 url_not_allowed.
  • Up to 5 endpoints per merchant and environment. You can subscribe to specific events or all of them.
  • When it is created you receive the secret (whsec_…) only once. Store it on your server.
curl -X POST "$CLOBEPAY_API_BASE/webhook-endpoints" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \  -H "Content-Type: application/json" \  -d '{"url":"https://api.comercioatlas.mx/webhooks/clobepay","eventTypes":["payin.settled","payin.expired","payout.completed"]}'

Response

HTTP 201
{
  "id": "we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6",
  "url": "https://api.comercioatlas.mx/webhooks/clobepay",
  "eventTypes": [
    "payin.settled",
    "payout.completed"
  ],
  "status": "enabled",
  "secret": "whsec_AtCJBGiga3h…"
}

Headers and signature

Headers on every delivery
Clobepay-Signature: t=1763445600,v1=5f2b…(hex sha256)[,v1=<firma con el secreto anterior | signature with the previous secret>]
Clobepay-Event-Id: evt_iS50IM4GXDwNpq1EZedhRJ
Clobepay-Event-Type: payin.settled
Clobepay-Delivery-Id: whd_7Qa…
Clobepay-Webhook-Version: 2026-11-17
User-Agent: Clobepay-Webhooks/1.0
Content-Type: application/json

v1 = hex(HMAC-SHA256(secret, t + "." + raw_body)). To verify:

  1. Read the raw body, before parsing the JSON.
  2. Take t and every v1 signature from Clobepay-Signature.
  3. Reject if |now − t| > 300 seconds.
  4. Compute the signature with your secret and compare it in constant time with each v1; one match is enough.
Node.js · verify the signature
// Node 18+. Usa el cuerpo CRUDO (Buffer) / use the RAW body (Buffer).
import crypto from 'node:crypto';

export function verifyClobepaySignature(rawBody, header, secret, toleranceSec = 300) {
  const t = Number(/(?:^|,)t=(\d+)/.exec(header ?? '')?.[1]);
  const signatures = [...(header ?? '').matchAll(/v1=([0-9a-f]{64})/g)].map((m) => m[1]);
  if (!t || signatures.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.`)
    .update(rawBody)
    .digest();
  // Durante una rotación llegan dos v1: basta con que una coincida.
  // During a rotation two v1 values arrive: one match is enough.
  return signatures.some((sig) => crypto.timingSafeEqual(Buffer.from(sig, 'hex'), expected));
}

Python · verify the signature
# Python 3. Usa el cuerpo CRUDO (bytes) / use the RAW body (bytes).
import hashlib, hmac, re, time

def verify_clobepay_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    m = re.search(r"(?:^|,)t=(\d+)", header or "")
    signatures = re.findall(r"v1=([0-9a-f]{64})", header or "")
    if not m or not signatures:
        return False
    t = int(m.group(1))
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), str(t).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    # Durante una rotación llegan dos v1 / during a rotation two v1 values arrive.
    return any(hmac.compare_digest(sig, expected) for sig in signatures)

Node.js (Express) · receive the event
// Express: responde 2xx rápido, deduplica por Clobepay-Event-Id y procesa después.
// Express: respond 2xx fast, deduplicate by Clobepay-Event-Id and process later.
import express from 'express';
import { verifyClobepaySignature } from './verify-clobepay.js';

const app = express();
app.post('/webhooks/clobepay', express.raw({ type: 'application/json' }), async (req, res) => {
  const ok = verifyClobepaySignature(
    req.body,
    req.get('Clobepay-Signature'),
    process.env.CLOBEPAY_WEBHOOK_SECRET,
  );
  if (!ok) return res.sendStatus(400);

  const isNew = await saveEventIdIfNew(req.get('Clobepay-Event-Id')); // índice único / unique index
  if (isNew) await enqueue(JSON.parse(req.body.toString('utf8')));
  res.sendStatus(200);
});

cURL · simulate a delivery to your endpoint
# Simula una entrega firmada contra TU endpoint (secreto del entorno de pruebas).
# Simulate a signed delivery to YOUR endpoint (test-environment secret).
WHSEC='whsec_solo_para_pruebas_locales'
T=$(date +%s)
BODY='{"id":"evt_test","type":"webhook_endpoint.test","data":{"object":{}}}'
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$WHSEC" | awk '{print $NF}')
curl -X POST "https://api.comercioatlas.mx/webhooks/clobepay" \
  -H "Clobepay-Signature: t=$T,v1=$SIG" \
  -H "Clobepay-Event-Id: evt_test" \
  -H "Clobepay-Event-Type: webhook_endpoint.test" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Event envelope

payin.settled
{
  "id": "evt_iS50IM4GXDwNpq1EZedhRJ",
  "type": "payin.settled",
  "apiVersion": "2026-11-17",
  "createdAt": "2026-11-18T06:00:00Z",
  "merchantId": "MID000847",
  "livemode": false,
  "data": {
    "object": {
      "object": "payin",
      "id": "pi_3Kx9mQ2vR8wL0tYbA4nC1e",
      "status": "settled",
      "source": "payment_link",
      "amount": "50.00",
      "asset": "USDT",
      "paymentLinkId": "7c2e1a4b-9d83-4f21-a6b0-2e8c91f04d17",
      "orderReference": "10042",
      "metadata": { "cart_id": "c_77" },
      "settledAt": "2026-11-18T06:00:00Z",
      "availableAt": "2026-11-18T06:00:00Z"
    },
    "previousAttributes": { "status": "pending" }
  }
}

No personal data of the payer or the signer; amounts as decimal strings. You only receive events from your own merchant.

Event catalog
ResourceEvents
Payment linkpayment_link.created, payment_link.expired
Payinpayin.created, payin.settled, payin.expired, payin.failed, payin.refunded
Deposit accountdeposit_account.created
Payoutpayout.created, payout.pending_approval, payout.approved, payout.rejected, payout.processing, payout.completed, payout.failed
KYC/KYBverification.submitted, verification.document_validated, verification.liveness_required, verification.liveness_completed, verification.changes_requested, verification.approved, verification.rejected
Testwebhook_endpoint.test

Delivery and retries

  • Success = any 2xx response within 10 seconds. Respond quickly and process in the background.
  • At-least-once delivery: deduplicate by Clobepay-Event-Id, which does not change between retries (Clobepay-Delivery-Id does).
  • Do not rely on arrival order: when in doubt, query the resource.
Retry schedule
AttemptWait after the previous one
1immediately
21 min
35 min
430 min
52 h
66 h
712 h
824 h
  • With ±20 % random jitter; about 45 hours in total. After the 8th failure the delivery is failed and you can resend it.
  • If you respond 410 Gone, the delivery becomes failed immediately.
  • If every delivery fails for 72 hours in a row, the endpoint is disabled automatically and you are notified in the dashboard.

Secret rotation

POST /webhook-endpoints/{id}/rotate-secret generates a new secret (shown once). During the grace period (expirePreviousInHours, 0 to 72; 24 by default) each delivery carries two v1 signatures: one with the new secret and one with the previous one. Deploy the new secret before the grace period ends.

POST/webhook-endpoints/{endpointId}/rotate-secret
curl -X POST "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6/rotate-secret" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \  -H "Content-Type: application/json" \  -d '{"expirePreviousInHours":24}'

Response

HTTP 200
New secret (only in this response).

Log, test and resend

  • POST /webhook-endpoints
  • GET /webhook-endpoints
  • PATCH /webhook-endpoints/{id}
  • DELETE /webhook-endpoints/{id}
  • POST /webhook-endpoints/{id}/rotate-secret
  • POST /webhook-endpoints/{id}/test
  • GET /webhook-endpoints/{id}/deliveries
  • GET /webhook-deliveries/{id}
  • POST /webhook-deliveries/{id}/resend
  • POST /webhook-endpoints/{id}/resend-failed

Bulk resend accepts up to 500 events per call. Deliveries are kept for 90 days.