Webhooks
Endpoints firmados hacia tu servidor y sus entregas.
Registra una URL HTTPS para recibir eventos (payin.*, payment_link.*, payout.*, verification.*, deposit_account.created, webhook_endpoint.test). Cada entrega lleva la cabecera Clobepay-Signature (t=…,v1=…), un HMAC-SHA256 del timestamp y el cuerpo crudo. Responde 2xx para acusar recibo; los errores y timeouts se reintentan con espera creciente hasta abandonarse. El secreto (whsec_…) se muestra solo al crear o rotar. POST /webhook-endpoints no exige Idempotency-Key. El cuerpo de alta y el objeto del evento usan camelCase (eventTypes, paymentLinkId, settledAt). Marca la orden como pagada solo con payin.settled.
- pending → in_flight: HTTPS a tu URL
- pending → abandoned: Endpoint deshabilitado
- in_flight → succeeded: 2xx
- in_flight → pending: Error o timeout (reintento)
- in_flight → failed: Sin más reintentos
Dar de alta un endpoint
/api/v1/webhook-endpoints
Registra tu URL. El secreto se muestra una sola vez. Scope webhooks:write.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
urlstringObligatorioURL HTTPS de tu servidor.
eventTypesstring[]OpcionalEventos a recibir. Si omites el campo, se suscribe a todos (*).
descriptionstringOpcionalEtiqueta interna.
Respuestas
- HTTP 201Endpoint + secreto (solo en esta respuesta). id es we_ + 22 caracteres; status es enabled, disabled o auto_disabled.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 409
webhook_endpoint_limitAlcanzaste el máximo de endpoints. - HTTP 422
url_must_be_httpsLa URL no usa https. - HTTP 422
url_not_allowedLa URL apunta a una dirección privada o interna, no resuelve en DNS, lleva credenciales o usa un puerto distinto de 443. - HTTP 422
invalid_urlLa URL no es válida. - HTTP 422
invalid_event_typeseventTypes trae tipos que no están en el catálogo.
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"]}'Respuesta
HTTP 201{
"id": "we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6",
"url": "https://api.comercioatlas.mx/webhooks/clobepay",
"eventTypes": [
"payin.settled",
"payout.completed"
],
"status": "enabled",
"secret": "whsec_AtCJBGiga3h…"
}Listar endpoints
/api/v1/webhook-endpoints
Tus URLs registradas, sin el secreto. Scope webhooks:read.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
Respuestas
- HTTP 200Listado.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After.
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200{
"items": []
}Consultar un endpoint
/api/v1/webhook-endpoints/{endpointId}
Detalle, sin el secreto.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
endpointIdstringObligatorioId del endpoint (we_ + 22 caracteres).
Respuestas
- HTTP 200Detalle.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200Detalle.Actualizar un endpoint
/api/v1/webhook-endpoints/{endpointId}
Cambia la URL, los eventos, la descripción o lo reactiva (enabled: true).
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
endpointIdstringObligatorioId del endpoint (we_ + 22 caracteres).
urlstringOpcionalNueva URL HTTPS.
eventTypesstring[]OpcionalNueva lista de eventos.
descriptionstringOpcionalNueva etiqueta.
enabledbooleanOpcionaltrue reactiva un endpoint disabled o auto_disabled y reinicia el conteo de fallos.
Respuestas
- HTTP 200Endpoint actualizado.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_…. - HTTP 422
url_must_be_httpsLa URL no usa https. - HTTP 422
url_not_allowedLa URL apunta a una dirección privada o interna, no resuelve en DNS, lleva credenciales o usa un puerto distinto de 443. - HTTP 422
invalid_urlLa URL no es válida. - HTTP 422
invalid_event_typeseventTypes trae tipos que no están en el catálogo.
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}'Respuesta
HTTP 200Endpoint actualizado.Eliminar un endpoint
/api/v1/webhook-endpoints/{endpointId}
Deja de enviar eventos a esa URL.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
endpointIdstringObligatorioId del endpoint (we_ + 22 caracteres).
Respuestas
- HTTP 204Eliminado.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
curl -X DELETE "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 204Eliminado.Rotar el secreto
/api/v1/webhook-endpoints/{endpointId}/rotate-secret
Nuevo whsec_…. El anterior sigue válidas un periodo de gracia (por defecto 24 h).
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
endpointIdstringObligatorioId del endpoint (we_ + 22 caracteres).
expirePreviousInHoursnumberOpcionalHoras de gracia del secreto anterior (0–72, por defecto 24).
Respuestas
- HTTP 200Nuevo secreto (solo en esta respuesta).
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
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}'Respuesta
HTTP 200Nuevo secreto (solo en esta respuesta).Enviar un evento de prueba
/api/v1/webhook-endpoints/{endpointId}/test
Despacha webhook_endpoint.test a tu URL.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
endpointIdstringObligatorioId del endpoint (we_ + 22 caracteres).
Respuestas
- HTTP 202Entrega encolada (deliveryId whd_…).
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
curl -X POST "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6/test" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 202Entrega encolada (deliveryId whd_…).Listar entregas
/api/v1/webhook-endpoints/{endpointId}/deliveries
Historial de envíos a ese endpoint.
Parámetros
AuthorizationstringObligatorioBearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.
endpointIdstringObligatorioId del endpoint (we_ + 22 caracteres).
statusstringOpcionalEstado de la entrega.
pending · in_flight · succeeded · failed · abandoned
eventTypestringOpcionalFiltra por tipo de evento (por ejemplo payin.settled).
fromstringOpcionalISO-8601.
tostringOpcionalISO-8601.
limitnumberOpcional1–100 (50 por defecto).
Respuestas
- HTTP 200Entregas en data; cada una con id whd_ + 22 caracteres, eventId, eventType, status y attempt.
Errores
- HTTP 400
ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas. - HTTP 401
missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key). - HTTP 401
invalid_api_keyLa llave no existe, está mal formada o no coincide. - HTTP 401
api_key_revokedLa llave fue revocada. - HTTP 401
api_key_expiredLa llave expiró. - HTTP 401
api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés). - HTTP 403
insufficient_scopeLa llave no tiene el scope de esta ruta. - HTTP 429
rate_limitedDemasiadas peticiones. Respeta Retry-After. - HTTP 404
not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6/deliveries?status=failed" \ -H "Authorization: Bearer $CLOBEPAY_API_KEY"Respuesta
HTTP 200Entregas en data; cada una con id whd_ + 22 caracteres, eventId, eventType, status y attempt.