Webhook entrante (contrato)
El webhook entrante es un forward: Kalipto recibe el POST original de Meta
en /webhook/incoming y, si matchea un canal de plataforma activo, te
reenvía el payload crudo re-firmado con tu secret. Como NO es una ruta de
nuestra API (somos nosotros los que llamamos a la tuya), no aparece en el
snapshot autogenerado del OpenAPI. Esta página resume el contrato; el detalle
completo vive en la guía.
Cabeceras del POST que recibís
Section titled “Cabeceras del POST que recibís”| Header | Valor |
|--------|-------|
| Content-Type | application/json |
| User-Agent | Kalipto-Platform/1.0 |
| X-Kalipto-Delivery-Id | id de platform_deliveries, persistente entre reintentos. |
| X-Kalipto-Signature | sha256=<hmac_hex> de los bytes exactos del body, usando tu webhook_secret como clave. Omitido si el canal no tiene secret. |
El JSON crudo de Meta verbatim. Sin envoltorio, sin wrapping. Lo que Meta nos mandó es lo que recibís.
La cabecera X-Hub-Signature-256 de Meta no se reenvía: la verificación es
contra X-Kalipto-Signature solamente. Tu secret es la verdad.
Verificación HMAC
Section titled “Verificación HMAC”Para que tu verificación produzca el mismo hex digest que firmamos, computá el HMAC-SHA256 sobre los bytes exactos del body que recibís, nunca sobre una re-serialización en tu stack. Detalle paso a paso en Verificación HMAC.
Reintentos y máquina de estados
Section titled “Reintentos y máquina de estados”Persistimos PlatformDelivery(status="pending") antes de hacer el POST.
Reintentos: 0, 1m, 5m, 30m, 120m. Después de 5 intentos fallidos
queda en failed. Cero pérdida por crash: si el proceso muere entre commit
y dispatch, el worker levanta el row con un sweep cada 10 segundos.
Solo los mensajes reales de usuarios cuentan contra plan.inbound_limit.
Los status callbacks de Meta (phone_number_quality_update,
message_template_status_update, account_update) se reenvían sin consumir
cupo.
Detalle completo
Section titled “Detalle completo”Ver Webhook entrante (forward) para la guía
con SSRF guard, lease de 2 minutos en delivering, serialización canónica
del body y garantías de entrega.