Webhooks — Resumen

Los webhooks son la señal autoritativa. Los callbacks del navegador (onSuccess) y las vistas del dashboard son conveniencia; los webhooks son la verdad de base.

Garantías de entrega

• Al menos una vez. Un solo evento puede entregarse hasta 6 veces si tu servidor no devuelve 2xx dentro del timeout. Haz tu handler idempotente: deduplica por X-Delivery (el payload no tiene un campo event_id; el UUID estable de la entrega es la clave de idempotencia).
• Un evento por petición HTTP. Sin batching.
• Aislamiento por endpoint. Si tienes múltiples endpoints registrados, cada uno obtiene su propia pista de entrega + reintento. Una URL de comerciante lenta no puede hambrear a las otras: cada host tiene su propio circuit breaker.
• Firmado. Cada payload lleva una cabecera X-Signature (y durante la ventana de 24 horas tras una rotación, también una X-Signature-Prev). Verifica antes de hacer nada con el body. Consulta Verificación de firma.

Tipos de evento suscribibles

El dashboard obtiene esta lista de GET /v1/webhooks/event-types para que el formulario de creación / edición de endpoints siempre coincida con lo que la plataforma realmente emite. Suscribirse a un evento que no enviamos será rechazado en el momento de la creación con un error claro.

Payload + cabeceras

El body HTTP es el objeto data específico del evento directamente. Sin envelope externo estilo Stripe: campos como el tipo de evento, delivery ID y timestamp de emisión viven en cabeceras en su lugar. Para payment.settled el body se ve así:

{
  "receipt_id":        "rcp_…",
  "order_id":          "ord_…",
  "payment_intent_id": "pin_…",
  "checkout_session_id": "cst_…",
  "merchant_id":       "mer_…",
  "customer_id":       "cus_…",
  "total":             "49.00",
  "currency":          "USD",
  "payment_method":    "crypto",
  "token":             "USDC",
  "network":           "polygon",
  "tx_hash":           "0x…",
  "deposit_address":   "0x…",
  "treasury_address":  "0x…",
  "amount_received":   "49.00",
  "confirmations":     5,
  "metadata":          { /* per-event */ }
}

Otros eventos llevan su propio set de campos: consulta los structs de publisher en payment-service/internal/domain/events.go para la forma canónica hasta que aterricen los docs por evento. Los nombres de campo son estables (lower snake_case); el tx hash on-chain es siempre tx_hash (no transaction_hash).

Cabeceras en la petición entrante

Content-Type:      application/json
X-Event:           payment.settled
X-Delivery:        7c9e6679-7425-40de-944b-e07fc1f90ae7
Idempotency-Key:   7c9e6679-7425-40de-944b-e07fc1f90ae7
X-Timestamp:       1729536000
X-Signature:       sha256=9a8b7c…
X-Signature-Prev:  sha256=fa31b2…    (solo durante la ventana de gracia de rotación)

Calendario de reintentos

Si tu endpoint no devuelve 2xx dentro del timeout, reintentamos en este calendario (timestamps relativos al primer intento):

Tras fallar el intento 6, la entrega se mueve a dead letter y se notifica al email de la cuenta del comerciante. Los eventos dead-lettered pueden reproducirse desde el panel Developers → Webhooks → Delivery history del dashboard, o directamente vía POST /v1/webhooks/deliveries/:id/replay. Cada replay crea una nueva fila de entrega con su propio X-Delivery: la cadena de auditoría se vincula de vuelta al original vía parent_delivery_id para que los reintentos-de-replays no ensombrezcan el evento fuente.

Registra un endpoint

Desde el dashboard del comerciante :

1. Developers → Webhooks → + Add endpoint
2. Pega tu URL: solo https://… (HTTP plano se rechaza; el formulario de creación también bloquea localhost, rangos de IP privadas y URLs que lleven userinfo)
3. Elige eventos a los que suscribirte (o * para todos)
4. Elige entorno: test o live (cada uno tiene su propio secreto; nunca se cruzan)
5. Guarda → el dashboard muestra el secreto de firma (whsec_…) una vez. Guárdalo en el lado del servidor; lo necesitarás para las próximas dos funciones.

Puedes registrar hasta 10 endpoints por entorno por comerciante (p. ej., uno para fulfillment de producción, uno para staging mirroring, uno para un notificador de Slack). Cada uno mantiene su propio estado de reintento, secreto y circuit breaker por host.

Acciones de ciclo de vida en cada endpoint

El menú ⋮ en cada tarjeta de endpoint muestra:

• Edit: cambia la URL, descripción o lista de suscripciones. La nueva URL se revalida con las mismas reglas de https:///SSRF que en la creación.
• Send Test: POSTea síncronamente un envelope webhook.test.ping firmado con tu secreto actual. El dashboard muestra el status HTTP, latencia y un fragmento de 512 bytes de tu respuesta. Salta el pipeline de RMQ para que la respuesta sea inmediata.
• Rotate Secret: genera un nuevo secreto. El anterior sigue válido por 24 horas (las entregas llevan tanto X-Signature como X-Signature-Prev durante la ventana para que los verificadores corriendo cualquiera de las claves sigan aceptando eventos mientras redespliegas).
• Reveal Secret: muestra de nuevo el secreto existente. Protegido por verificación 2FA reciente y registrado en el log de auditoría; úsalo solo cuando hayas perdido tu copia y Rotate no sea aceptable.
• Enable / Disable: cambia is_active sin perder el historial de entregas. Los endpoints deshabilitados permanecen en el dashboard pero no reciben nuevas entregas.
• Delete: permanente. Usa Disable si podrías re-habilitar más tarde.

Consejos para handlers

1. Devuelve 2xx rápido. Confirma con 200 OK antes de hacer trabajo pesado: lanza el fulfillment a una cola en background. El timeout por intento es de 10 segundos; retener la respuesta más allá de eso dispara un reintento. El timeout es del lado de la plataforma y no es configurable por comerciante: contacta con soporte si tu handler genuinamente necesita más tiempo.
2. Deduplica por X-Delivery (o Idempotency-Key: mismo valor). Aunque devuelvas 2xx, un proxy aguas arriba podría soltar la conexión y disparar un reintento; el delivery ID es estable a través de cada reintento de la misma fila de entrega, así que es la clave correcta.
3. Tolera tipos de evento desconocidos. Pueden aparecer nuevos eventos; devuelve 200 y no-op en lugar de 4xx, o llenarás la cola de reintentos.
4. Loguea X-Delivery junto a tu lógica de negocio. Cuando algo va mal, esa es la clave de join entre nuestro lado y el tuyo.

Qué sigue

• Verificación de firma: el algoritmo exacto + patrones de protección contra replay.
• Conceptos → Sesiones: en qué estado está una sesión cuando cada evento se dispara.