Webhooks
Te avisamos al instante de cada cambio. Firmados, con reintentos y en orden.
curl "$CAIBO_API/v1/webhook-endpoints" \
-H "Authorization: Bearer $CAIBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://tu-empresa.com/webhooks/caibo",
"description": "Producción",
"event_types": ["payin.completed", "payout.completed", "payout.failed"]
}'url:https, pública, en el puerto 443.event_types: los tipos que quieres recibir. Vacío u omitido: todos.- La respuesta trae
secret(whsec_…) una sola vez. Si lo pierdes, rótalo. - Hasta 10 webhooks por cuenta y por entorno.
Lo que recibes
POST /webhooks/caibo HTTP/1.1
Content-Type: application/json
User-Agent: psp-webhooks/1 (live)
Psp-Signature: t=1790769600,v1=c0c9eaafdea23b0f8c992b380b286917c6459b0729b2496b8452fa695215e6b8
Psp-Event-Id: evt_01m3sgb02af7nb0jf73vwv2sd5
Psp-Delivery-Id: whd_01m3sgb03a...
Psp-Delivery-Attempt: 1{
"id": "evt_01m3sgb02af7nb0jf73vwv2sd5",
"type": "payout.completed",
"schema_version": 1,
"occurred_at": "2026-10-18T14:00:41.126938Z",
"livemode": true,
"data": { "id": "pout_01m3sgb02af7nb0jf73vwv2sd4", "status": "completed" }
}data es el recurso completo, con la misma forma que te da la API. Ver Eventos.
Cómo responder
Verifica la firma
Con el cuerpo tal como llegó, antes de parsearlo. Ver Firmas.
Responde 2xx enseguida
Tienes 10 segundos. Guarda el evento y procésalo después, en una cola. El cuerpo de tu respuesta se ignora. Una redirección (3xx) cuenta como fallo.
Descarta repetidos
La entrega es "al menos una vez": el mismo evento puede llegar dos veces. Usa Psp-Event-Id (el id del evento) para no procesarlo dos veces.
Reintentos
Si no respondes 2xx a tiempo, reintentamos hasta 10 veces en unas 23 horas:
| Intento | Espera antes | Intento | Espera antes | |
|---|---|---|---|---|
| 2 | 30 s | 7 | 2 h | |
| 3 | 2 min | 8 | 4 h | |
| 4 | 10 min | 9 | 8 h | |
| 5 | 30 min | 10 | 8 h | |
| 6 | 1 h |
Cada espera varía ±20 %. Después de 10 fallos seguidos, el webhook pasa a failing y le enviamos una entrega de prueba cada 15 minutos; la primera que responde bien lo devuelve a active. Ningún evento se pierde: siempre está en GET /v1/events.
Orden: una entrega a la vez por webhook, y los eventos de un mismo recurso llegan en orden.
Herramientas
| POST/v1/webhook-endpoints/{id}/ping | Envía un webhook.ping de prueba (hasta 5 por minuto). |
| GET/v1/webhook-endpoints/{id}/deliveries | El historial de entregas, con su estado y error. |
| POST/v1/events/{id}/redeliver | Reenvía un evento a todos tus webhooks, o solo a endpoint_id. |
| PATCH/v1/webhook-endpoints/{id} | Cambia url, description, event_types o pausa con active: false. |
Rotar el secreto
POST/v1/webhook-endpoints/{id}/rotate-secretDevuelve un secret nuevo. Durante 24 horas firmamos con los dos (el nuevo primero), así actualizas tu servidor sin perder avisos. previous_secret_expires_at dice cuándo deja de valer el anterior.