Webhooks API

Objetivo

Ingerir eventos Stripe con verificación de firma, deduplicación por evento y replay controlado para recuperación de incidentes.

Endpoints principales

Modelo de procesamiento

1. 11) Recibir evento

   Validar firma y estructura mínima del payload.

2. 22) Deduplicar

   Usar event.id del proveedor como clave de deduplicación; los duplicados devuelven duplicate: true.

3. 33) Persistir y procesar

   Guardar webhookEventId interno y ejecutar handlers asíncronos de forma segura.

4. 44) Confirmar estado

   Actualizar estado funcional y métricas de entrega; billing puede hacer upsert de suscripciones.

URLs canónicas por entorno

• test: https://test.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=test
• live: https://app.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=live
• Si usas el endpoint dedicado de billing, mantén la misma convención en /api/webhooks/stripe/billing.

Política de retries y replay

• Los retries automáticos deben preservar el contexto original.
• El replay manual usa el identificador interno webhookEventId, no el event.id de Stripe.
• Evita replay masivo sin priorización por impacto y criterios de validación explícitos.

Ejemplo de respuesta del endpoint general

{
  "ok": true,
  "webhookEventId": "whevt_123",
  "eventId": "evt_123",
  "mode": "test",
  "duplicate": false
}

Ejemplo de replay manual

curl -X POST "https://test.beacon.pt/api/billing/webhooks/whevt_123/replay?org=acme&mode=test" \
  -H "Authorization: Bearer <beacon_session_token>"

Señales operativas