Webhooks API

Objetivo

Ingerir eventos Stripe com validação criptográfica, deduplicação por evento e capacidade de replay controlado para recuperação operacional.

Endpoints principais

Modelo de processamento

1. 11) Receber evento

   Validar assinatura e formato mínimo do payload.

2. 22) Deduplicar

   Usar event.id como chave lógica de deduplicação; duplicados devolvem duplicate: true.

3. 33) Persistir e processar

   Guardar webhookEventId interno e executar o pipeline assíncrono.

4. 44) Confirmar estado

   Atualizar estado funcional e métricas de entrega; billing pode upsertar subscrições.

URLs canónicas por ambiente

• 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
• Se usares o endpoint dedicado de billing, mantém a mesma convenção em /api/webhooks/stripe/billing.

Política de retries e replay

• Retries automáticos devem manter contexto original do evento.
• Replay manual usa o identificador interno webhookEventId, não o event.id da Stripe.
• Nunca executar replay massivo sem priorização por impacto e sem janela de controlo.

Exemplo de resposta do endpoint geral

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

Exemplo 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>"

{
  "ok": true,
  "webhookEventId": "whevt_123",
  "queueJobId": "job_123",
  "replayScheduled": true,
  "context": {
    "mode": "test",
    "organizationSlug": "acme"
  }
}

Erros e sinais operacionais