Skip to main content

​
Esquema

CampoTipoDescrição
webhookIdUUIDv7Identificador único
externalRefstringID do evento no Stripe, máx 400
providerenumSTRIPE
eventTypestringTipo do evento Stripe, máx 255
headersJSONHeaders da requisição
bodyJSONBody da requisição
signaturestringAssinatura HMAC
statusenumPENDING, PROCESSING, PROCESSED, FAILED
attemptsintegerTentativas de processamento (padrão 0)
errorsJSON?Detalhes de erros
receivedAtdatetimeQuando foi recebido
processedAtdatetime?Quando foi processado
createdAtdatetimeCriação
updatedAtdatetimeÚltima atualização
Webhooks são o mecanismo principal de sincronização entre o Stripe e o domínio Billing. Eventos como invoice.paid, invoice.payment_failed, customer.subscription.updated disparam atualizações de estado nas entidades locais (Invoice, Subscription, etc.).

​
Transições de Estado

​
Regras de Negócio

  • Constraint único: (provider, externalRef)
  • Assinatura HMAC validada no recebimento
  • Webhooks com falha podem ser retentados (attempts incrementado)
  • Apenas log de auditoria — sem relacionamentos diretos com outras entidades
A validação da assinatura HMAC é obrigatória e acontece antes de qualquer processamento. Webhooks com assinatura inválida são rejeitados com HTTP 401 e não são persistidos no banco.
O campo errors armazena detalhes estruturados de cada falha, incluindo stack trace e contexto. Use isso para debugging — webhooks com status: FAILED após múltiplas tentativas geralmente indicam problemas de dados (ex: organização não encontrada, subscription inexistente).

​
Exemplo

{
  "webhookId": "01952af7-9ca1-7f1d-b0e8-4a6c2e8d0f3b",
  "externalRef": "evt_1PqR2sT4uV6wX8yZ0AbC",
  "provider": "STRIPE",
  "eventType": "invoice.paid",
  "headers": {
    "stripe-signature": "t=1711234567,v1=abc123def456..."
  },
  "body": {
    "id": "evt_1PqR2sT4uV6wX8yZ0AbC",
    "type": "invoice.paid",
    "data": {
      "object": {
        "id": "in_1PqR2sT4uV6wX8yZ0A",
        "status": "paid",
        "amount_paid": 23920,
        "currency": "brl"
      }
    }
  },
  "signature": "t=1711234567,v1=abc123def456...",
  "status": "PROCESSED",
  "attempts": 1,
  "errors": null,
  "receivedAt": "2026-03-15T14:32:10Z",
  "processedAt": "2026-03-15T14:32:11Z",
  "createdAt": "2026-03-15T14:32:10Z",
  "updatedAt": "2026-03-15T14:32:11Z"
}