Skip to main content
Este evento é publicado quando o sistema de faturamento recebe um webhook de um provedor de pagamento (ex.: Stripe) e valida sua assinatura com sucesso. Ele representa o ponto de ingestão bruta para eventos externos de faturamento — antes de qualquer processamento específico do domínio. O webhook é armazenado com seus headers, body e assinatura completos para fins de auditoria. Após publicar este evento, um processador downstream o captura, interpreta o tipo de evento específico do provedor e dispara os eventos de domínio apropriados (como invoice.paid ou invoice.payment_failed).
O webhook é persistido com status PENDING ao ser recebido. Ele transiciona por PROCESSING e depois para PROCESSED ou FAILED. O contador attempts rastreia quantas vezes o processamento foi tentado, habilitando lógica de retentativa para falhas transitórias.
Ao tratar este evento, sempre valide o campo signature contra o signing secret do provedor antes de confiar no payload. O campo eventType contém a classificação própria do provedor para o evento (ex.: invoice.paid para Stripe) — use-o para rotear para a lógica de processamento correta. Deduplique pelo externalRef para prevenir o processamento do mesmo evento do provedor duas vezes.

​
Detalhes do Evento

PropriedadeValor
Typewebhook.received

​
Schema do Payload

​
webhookId
string (UUID v7)
required
Identificador do registro de webhook.
​
externalRef
string
required
ID do evento do provedor.
​
provider
string
required
Provedor de pagamento: STRIPE.
​
eventType
string
required
Tipo de evento do provedor (ex.: invoice.paid).
​
headers
object
required
Headers da requisição.
​
body
object
required
Body da requisição.
​
signature
string
required
Assinatura HMAC.
​
status
string
required
Status de processamento: PENDING, PROCESSING, PROCESSED ou FAILED.
​
attempts
integer
required
Contagem de tentativas de processamento.
​
errors
object
Detalhes do erro.
​
receivedAt
string (ISO 8601)
required
Quando o webhook foi recebido.
​
processedAt
string (ISO 8601)
Quando o webhook foi processado.
​
createdAt
string (ISO 8601)
required
Timestamp de criação.
​
updatedAt
string (ISO 8601)
required
Timestamp da última atualização.
{
  "specversion": "1.0",
  "type": "webhook.received",
  "id": "evt_0195f3a2-8c00-7d4e-b804-4d5e6f7a8b9c",
  "time": "2026-03-25T14:00:00Z",
  "datacontenttype": "application/json",
  "data": {
    "webhookId": "0195f3a2-8c00-7d4e-b804-4d5e6f7a8b9c",
    "externalRef": "evt_abc123",
    "provider": "STRIPE",
    "eventType": "invoice.paid",
    "headers": {
      "stripe-signature": "t=1234567890,v1=abc..."
    },
    "body": {
      "id": "evt_abc123",
      "type": "invoice.paid",
      "data": {}
    },
    "signature": "t=1234567890,v1=abc...",
    "status": "PENDING",
    "attempts": 0,
    "errors": null,
    "receivedAt": "2026-03-25T14:00:00Z",
    "processedAt": null,
    "createdAt": "2026-03-25T14:00:00Z",
    "updatedAt": "2026-03-25T14:00:00Z"
  }
}