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.
- 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
Create an endpoint
/api/v1/webhook-endpoints
Register your URL. The secret is shown once. Scope webhooks:write.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
urlstringRequiredHTTPS URL of your server.
eventTypesstring[]OptionalEvents to receive. If omitted, subscribes to all (*).
descriptionstringOptionalInternal label.
Responses
- HTTP 201Endpoint + secret (only in this response). id is we_ + 22 characters; status is enabled, disabled or auto_disabled.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 409
webhook_endpoint_limitYou reached the endpoint limit. - HTTP 422
url_must_be_httpsThe URL does not use https. - HTTP 422
url_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 422
invalid_urlThe URL is not valid. - HTTP 422
invalid_event_typeseventTypes has types that are not in the catalog.
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…"
}List endpoints
/api/v1/webhook-endpoints
Your registered URLs, without the secret. Scope webhooks:read.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
Responses
- HTTP 200List.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After.
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200{
"items": []
}Retrieve an endpoint
/api/v1/webhook-endpoints/{endpointId}
Detail, without the secret.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
endpointIdstringRequiredEndpoint id (we_ + 22 characters).
Responses
- HTTP 200Detail.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200Detail.Update an endpoint
/api/v1/webhook-endpoints/{endpointId}
Change the URL, events, description, or re-enable it (enabled: true).
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
endpointIdstringRequiredEndpoint id (we_ + 22 characters).
urlstringOptionalNew HTTPS URL.
eventTypesstring[]OptionalNew event list.
descriptionstringOptionalNew label.
enabledbooleanOptionaltrue re-enables a disabled or auto_disabled endpoint and resets the failure count.
Responses
- HTTP 200Endpoint updated.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundIt does not exist or is not yours, or endpointId is not in the we_… format. - HTTP 422
url_must_be_httpsThe URL does not use https. - HTTP 422
url_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 422
invalid_urlThe URL is not valid. - HTTP 422
invalid_event_typeseventTypes has types that are not in the catalog.
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 200Endpoint updated.Delete an endpoint
/api/v1/webhook-endpoints/{endpointId}
Stops sending events to that URL.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
endpointIdstringRequiredEndpoint id (we_ + 22 characters).
Responses
- HTTP 204Deleted.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
curl -X DELETE "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 204Deleted.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
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
endpointIdstringRequiredEndpoint id (we_ + 22 characters).
expirePreviousInHoursnumberOptionalGrace hours for the previous secret (0–72, default 24).
Responses
- HTTP 200New secret (only in this response).
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
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).Send a test event
/api/v1/webhook-endpoints/{endpointId}/test
Dispatches webhook_endpoint.test to your URL.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
endpointIdstringRequiredEndpoint id (we_ + 22 characters).
Responses
- HTTP 202Delivery queued (deliveryId whd_…).
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
curl -X POST "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6/test" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 202Delivery queued (deliveryId whd_…).List deliveries
/api/v1/webhook-endpoints/{endpointId}/deliveries
Send history for that endpoint.
Parameters
AuthorizationstringRequiredBearer $CLOBEPAY_API_KEY. X-API-Key with the same value is also accepted. Do not send both.
endpointIdstringRequiredEndpoint id (we_ + 22 characters).
statusstringOptionalDelivery status.
pending · in_flight · succeeded · failed · abandoned
eventTypestringOptionalFilter by event type (for example payin.settled).
fromstringOptionalISO-8601.
tostringOptionalISO-8601.
limitnumberOptional1–100 (default 50).
Responses
- HTTP 200Deliveries in data; each one with id whd_ + 22 characters, eventId, eventType, status and attempt.
Errors
- HTTP 400
ambiguous_credentialsAuthorization: Bearer and X-API-Key carry different keys. - HTTP 401
missing_credentialsNo key was sent (Authorization: Bearer or X-API-Key). - HTTP 401
invalid_api_keyThe key does not exist, is malformed or does not match. - HTTP 401
api_key_revokedThe key was revoked. - HTTP 401
api_key_expiredThe key expired. - HTTP 401
api_key_wrong_environmentThe key belongs to another environment (test key in live, or the other way around). - HTTP 403
insufficient_scopeThe key does not have the scope for this route. - HTTP 429
rate_limitedToo many requests. Honour Retry-After. - HTTP 404
not_foundIt does not exist or is not yours, or endpointId is not in the we_… format.
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6/deliveries?status=failed" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Response
HTTP 200Deliveries in data; each one with id whd_ + 22 characters, eventId, eventType, status and attempt.