Volver a la referencia

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.

Entrega de un webhook
  • 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
POST

Dar de alta un endpoint

/api/v1/webhook-endpoints

Registra tu URL. El secreto se muestra una sola vez. Scope webhooks:write.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

url
body
stringObligatorio

URL HTTPS de tu servidor.

eventTypes
body
string[]Opcional

Eventos a recibir. Si omites el campo, se suscribe a todos (*).

description
body
stringOpcional

Etiqueta interna.

Respuestas

  • HTTP 201Endpoint + secreto (solo en esta respuesta). id es we_ + 22 caracteres; status es enabled, disabled o auto_disabled.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 409webhook_endpoint_limitAlcanzaste el máximo de endpoints.
  • HTTP 422url_must_be_httpsLa URL no usa https.
  • HTTP 422url_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 422invalid_urlLa URL no es válida.
  • HTTP 422invalid_event_typeseventTypes trae tipos que no están en el catálogo.
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"]}'

Respuesta

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

GET

Listar endpoints

/api/v1/webhook-endpoints

Tus URLs registradas, sin el secreto. Scope webhooks:read.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

Respuestas

  • HTTP 200Listado.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
GET/webhook-endpoints
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
{
  "items": []
}

GET

Consultar un endpoint

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

Detalle, sin el secreto.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

endpointId
path
stringObligatorio

Id del endpoint (we_ + 22 caracteres).

Respuestas

  • HTTP 200Detalle.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 404not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
GET/webhook-endpoints/{endpointId}
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
Detalle.

PATCH

Actualizar un endpoint

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

Cambia la URL, los eventos, la descripción o lo reactiva (enabled: true).

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

endpointId
path
stringObligatorio

Id del endpoint (we_ + 22 caracteres).

url
body
stringOpcional

Nueva URL HTTPS.

eventTypes
body
string[]Opcional

Nueva lista de eventos.

description
body
stringOpcional

Nueva etiqueta.

enabled
body
booleanOpcional

true reactiva un endpoint disabled o auto_disabled y reinicia el conteo de fallos.

Respuestas

  • HTTP 200Endpoint actualizado.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 404not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
  • HTTP 422url_must_be_httpsLa URL no usa https.
  • HTTP 422url_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 422invalid_urlLa URL no es válida.
  • HTTP 422invalid_event_typeseventTypes trae tipos que no están en el catálogo.
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}'

Respuesta

HTTP 200
Endpoint actualizado.

DELETE

Eliminar un endpoint

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

Deja de enviar eventos a esa URL.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

endpointId
path
stringObligatorio

Id del endpoint (we_ + 22 caracteres).

Respuestas

  • HTTP 204Eliminado.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 404not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
DELETE/webhook-endpoints/{endpointId}
curl -X DELETE "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 204
Eliminado.

POST

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

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

endpointId
path
stringObligatorio

Id del endpoint (we_ + 22 caracteres).

expirePreviousInHours
body
numberOpcional

Horas de gracia del secreto anterior (0–72, por defecto 24).

Respuestas

  • HTTP 200Nuevo secreto (solo en esta respuesta).

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 404not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
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}'

Respuesta

HTTP 200
Nuevo secreto (solo en esta respuesta).

POST

Enviar un evento de prueba

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

Despacha webhook_endpoint.test a tu URL.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

endpointId
path
stringObligatorio

Id del endpoint (we_ + 22 caracteres).

Respuestas

  • HTTP 202Entrega encolada (deliveryId whd_…).

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 404not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
POST/webhook-endpoints/{endpointId}/test
curl -X POST "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6/test" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 202
Entrega encolada (deliveryId whd_…).

GET

Listar entregas

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

Historial de envíos a ese endpoint.

Parámetros

Authorization
header
stringObligatorio

Bearer $CLOBEPAY_API_KEY. También se acepta X-API-Key con el mismo valor. No envíes ambos.

endpointId
path
stringObligatorio

Id del endpoint (we_ + 22 caracteres).

status
query
stringOpcional

Estado de la entrega.

pending · in_flight · succeeded · failed · abandoned

eventType
query
stringOpcional

Filtra por tipo de evento (por ejemplo payin.settled).

from
query
stringOpcional

ISO-8601.

to
query
stringOpcional

ISO-8601.

limit
query
numberOpcional

1–100 (50 por defecto).

Respuestas

  • HTTP 200Entregas en data; cada una con id whd_ + 22 caracteres, eventId, eventType, status y attempt.

Errores

  • HTTP 400ambiguous_credentialsAuthorization: Bearer y X-API-Key traen llaves distintas.
  • HTTP 401missing_credentialsNo enviaste la llave (Authorization: Bearer o X-API-Key).
  • HTTP 401invalid_api_keyLa llave no existe, está mal formada o no coincide.
  • HTTP 401api_key_revokedLa llave fue revocada.
  • HTTP 401api_key_expiredLa llave expiró.
  • HTTP 401api_key_wrong_environmentLa llave es de otro ambiente (llave de prueba en producción o al revés).
  • HTTP 403insufficient_scopeLa llave no tiene el scope de esta ruta.
  • HTTP 429rate_limitedDemasiadas peticiones. Respeta Retry-After.
  • HTTP 404not_foundNo existe o no es tuyo, o endpointId no tiene el formato we_….
GET/webhook-endpoints/{endpointId}/deliveries
curl -X GET "$CLOBEPAY_API_BASE/webhook-endpoints/we_4Lq8Zt2Rk9Xw1Vb7Nc3Hd6/deliveries?status=failed" \  -H "Authorization: Bearer $CLOBEPAY_API_KEY"

Respuesta

HTTP 200
Entregas en data; cada una con id whd_ + 22 caracteres, eventId, eventType, status y attempt.