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.
- 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
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/jsonv1 = hex(HMAC-SHA256(secret, t + "." + raw_body)). To verify:
- Read the raw body, before parsing the JSON.
- Take
tand everyv1signature fromClobepay-Signature. - Reject if
|now − t| > 300seconds. - Compute the signature with your secret and compare it in constant time with each
v1; one match is enough.
// 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 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)// 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);
});# 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
{
"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
| Resource | Events |
|---|---|
| Payment link | payment_link.created, payment_link.expired |
| Payin | payin.created, payin.settled, payin.expired, payin.failed, payin.refunded |
| Deposit account | deposit_account.created |
| Payout | payout.created, payout.pending_approval, payout.approved, payout.rejected, payout.processing, payout.completed, payout.failed |
| KYC/KYB | verification.submitted, verification.document_validated, verification.liveness_required, verification.liveness_completed, verification.changes_requested, verification.approved, verification.rejected |
| Test | webhook_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-Iddoes). - Do not rely on arrival order: when in doubt, query the resource.
| Attempt | Wait after the previous one |
|---|---|
| 1 | immediately |
| 2 | 1 min |
| 3 | 5 min |
| 4 | 30 min |
| 5 | 2 h |
| 6 | 6 h |
| 7 | 12 h |
| 8 | 24 h |
- With ±20 % random jitter; about 45 hours in total. After the 8th failure the delivery is
failedand you can resend it. - If you respond
410 Gone, the delivery becomesfailedimmediately. - 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.
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 200New secret (only in this response).Log, test and resend
POST /webhook-endpointsGET /webhook-endpointsPATCH /webhook-endpoints/{id}DELETE /webhook-endpoints/{id}POST /webhook-endpoints/{id}/rotate-secretPOST /webhook-endpoints/{id}/testGET /webhook-endpoints/{id}/deliveriesGET /webhook-deliveries/{id}POST /webhook-deliveries/{id}/resendPOST /webhook-endpoints/{id}/resend-failed
Bulk resend accepts up to 500 events per call. Deliveries are kept for 90 days.