Back to the reference

Webhooks

Signed endpoints to your server and their deliveries.

Register an HTTPS URL to receive events (payin.*, payment_link.*, payout.*, verification.*, deposit_account.created, webhook_endpoint.test). Every delivery includes the Clobepay-Signature header (t=…,v1=…), an HMAC-SHA256 of the timestamp and the raw body. Respond 2xx to acknowledge; errors and timeouts are retried with backoff until they are abandoned. The secret (whsec_…) is shown only when you create or rotate it. POST /webhook-endpoints does not require Idempotency-Key. The create body and the event object use camelCase (eventTypes, paymentLinkId, settledAt). Mark the order paid only on payin.settled.

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
POST

Create an endpoint

/api/v1/webhook-endpoints

Register your URL. The secret is shown once. Scope webhooks:write.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

url
body
stringRequired

HTTPS URL of your server.

eventTypes
body
string[]Optional

Events to receive. If omitted, subscribes to all (*).

description
body
stringOptional

Internal label.

Responses

  • HTTP 201Endpoint + secret (only in this response). id is we_ + 22 characters; status is enabled, disabled or auto_disabled.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 409webhook_endpoint_limitYou reached the endpoint limit.
  • HTTP 422url_must_be_httpsThe URL does not use https.
  • HTTP 422url_not_allowedThe URL points to a private or internal address, does not resolve in DNS, carries credentials or uses a port other than 443.
  • HTTP 422invalid_urlThe URL is not valid.
  • HTTP 422invalid_event_typeseventTypes has types that are not in the catalog.
POST/webhook-endpoints
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…"
}

GET

List endpoints

/api/v1/webhook-endpoints

Your registered URLs, without the secret. Scope webhooks:read.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

Responses

  • HTTP 200List.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
GET/webhook-endpoints
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
{
  "items": []
}

GET

Retrieve an endpoint

/api/v1/webhook-endpoints/{endpointId}

Detail, without the secret.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

endpointId
path
stringRequired

Endpoint id (we_ + 22 characters).

Responses

  • HTTP 200Detail.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
GET/webhook-endpoints/{endpointId}
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
Detail.

PATCH

Update an endpoint

/api/v1/webhook-endpoints/{endpointId}

Change the URL, events, description, or re-enable it (enabled: true).

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

endpointId
path
stringRequired

Endpoint id (we_ + 22 characters).

url
body
stringOptional

New HTTPS URL.

eventTypes
body
string[]Optional

New event list.

description
body
stringOptional

New label.

enabled
body
booleanOptional

true re-enables a disabled or auto_disabled endpoint and resets the failure count.

Responses

  • HTTP 200Endpoint updated.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
  • HTTP 422url_must_be_httpsThe URL does not use https.
  • HTTP 422url_not_allowedThe URL points to a private or internal address, does not resolve in DNS, carries credentials or uses a port other than 443.
  • HTTP 422invalid_urlThe URL is not valid.
  • HTTP 422invalid_event_typeseventTypes has types that are not in the catalog.
PATCH/webhook-endpoints/{endpointId}
curl -X PATCH "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY" \  -H "Content-Type: application/json" \  -d '{"eventTypes":["payin.settled"],"enabled":true}'

Response

HTTP 200
Endpoint updated.

DELETE

Delete an endpoint

/api/v1/webhook-endpoints/{endpointId}

Stops sending events to that URL.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

endpointId
path
stringRequired

Endpoint id (we_ + 22 characters).

Responses

  • HTTP 204Deleted.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
DELETE/webhook-endpoints/{endpointId}
curl -X DELETE "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 204
Deleted.

POST

Rotate the secret

/api/v1/webhook-endpoints/{endpointId}/rotate-secret

New whsec_…. The previous one stays valid for a grace period (24 h by default).

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

endpointId
path
stringRequired

Endpoint id (we_ + 22 characters).

expirePreviousInHours
body
numberOptional

Grace hours for the previous secret (0–72, default 24).

Responses

  • HTTP 200New secret (only in this response).

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
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).

POST

Send a test event

/api/v1/webhook-endpoints/{endpointId}/test

Dispatches webhook_endpoint.test to your URL.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

endpointId
path
stringRequired

Endpoint id (we_ + 22 characters).

Responses

  • HTTP 202Delivery queued (deliveryId whd_…).

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
POST/webhook-endpoints/{endpointId}/test
curl -X POST "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6/test" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 202
Delivery queued (deliveryId whd_…).

GET

List deliveries

/api/v1/webhook-endpoints/{endpointId}/deliveries

Send history for that endpoint.

Parameters

Authorization
header
stringRequired

Bearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.

endpointId
path
stringRequired

Endpoint id (we_ + 22 characters).

status
query
stringOptional

Delivery status.

pending · in_flight · succeeded · failed · abandoned

eventType
query
stringOptional

Filter by event type (for example payin.settled).

from
query
stringOptional

ISO-8601.

to
query
stringOptional

ISO-8601.

limit
query
numberOptional

1–100 (default 50).

Responses

  • HTTP 200Deliveries in data; each one with id whd_ + 22 characters, eventId, eventType, status and attempt.

Errors

  • HTTP 400ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys.
  • HTTP 401missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key).
  • HTTP 401invalid_api_keyThe key does not exist, is malformed or does not match.
  • HTTP 401api_key_revokedThe key was revoked.
  • HTTP 401api_key_expiredThe key expired.
  • HTTP 401api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around).
  • HTTP 403insufficient_scopeThe key does not have the scope for this route.
  • HTTP 429rate_limitedToo many requests. Honour Retry-After.
  • HTTP 404not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
GET/webhook-endpoints/{endpointId}/deliveries
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6/deliveries?status=failed" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Response

HTTP 200
Deliveries in data; each one with id whd_ + 22 characters, eventId, eventType, status and attempt.