Estrutura da entrega (envelope)
Toda entrega é um POST com Content-Type: application/json e o corpo abaixo:{
"EventType": "Pix.CreditoRecebido",
"EventVersion": "v1",
"EventId": "550e8400-e29b-41d4-a716-446655440000",
"EntityId": "123456",
"OccurredAt": "2026-06-30T12:00:01Z",
"Data": {
"...": "campos específicos do evento — ver documentação de cada evento"
}
}
| Campo | Tipo | Descrição |
|---|
EventType | string | Nome do evento, no formato {Domínio}.{NomeEvento}. |
EventVersion | string | Versão do schema do evento. |
EventId | UUID | Identificador único desta entrega. Use-o para garantir idempotência — o mesmo evento pode ser entregue mais de uma vez em cenários de retentativa. Idêntico ao header Webhook-Id. |
EntityId | string | Identificador da entidade principal do evento — varia por tipo de evento, ver documentação específica. |
OccurredAt | string | Timestamp ISO 8601 (UTC) de quando o evento foi processado pela plataforma — não necessariamente o instante exato da ocorrência original no sistema de origem. |
Data | objeto | Payload do evento. |
| Header | Exemplo | Descrição |
|---|
Content-Type | application/json | Sempre application/json. |
Webhook-Id | 550e8400-... | Mesmo valor de EventId. Identifica unicamente esta entrega — use para deduplicação. |
Webhook-Timestamp | 1749772800 | Timestamp Unix, em segundos, do momento do envio. |
Webhook-Signature | v1a,MEcCIG... | Assinatura Ed25519 do conteúdo entregue. Prefixo v1a, seguido da assinatura em Base64. |
Webhook-Key-Id | 2026-07 | Identificador (kid) da chave usada para assinar esta entrega. Use para localizar a chave pública correta durante uma rotação de chaves — veja Autenticidade — assinatura Ed25519. |
Headers adicionais configurados na sua configuração de webhook também são enviados em toda entrega.
Versionamento#
Cada evento tem uma versão explícita (EventVersion), independente do envelope.Novos campos podem ser adicionados ao Data sem mudança de versão — trate campos desconhecidos em Data como ignoráveis, não como erro.
Remoção de campos, renomeação, ou mudança de semântica de um campo existente só ocorre em uma nova versão (v2, v3, …).
Ao lançar uma nova versão, a versão anterior continua ativa por um período de transição combinado previamente.
Modificado em 2026-08-12 21:04:50
