O objetivo da lista abaixo é ajudar a integração e não contém uma lista exaustiva de requisitos para a ativação em produção. Consulte o suporte Pinbank para mais informações.
Consultar nossa chave pública de assinatura de mensagens e guardar — não consultar a cada entrega recebida.
Ao receber eventos, validar a seleção da chave pública correta em jwks.keys pelo kid recebido no header Webhook-Key-Id — pode haver mais de uma chave ativa durante uma rotação.
Verificar a assinatura Ed25519 usando o corpo bruto da requisição. Não reserializar o JSON antes de validar.
Correlacionar os eventos de uma mesma transação/entidade pelo EntityId do envelope (semântica varia por domínio — NSU, E2E, CPF, nosso número).
Não tratar a presença/ausência isolada de um evento como sinal definitivo de sucesso ou falha sem checar Status/Data.status — vários eventos deste catálogo cobrem sucesso e erro no mesmo EventType (ex.: ContaDigital.CadastroPf, Boleto.Baixa, todos os eventos Compra.*).
Tratar valores de devolução/baixa parcial como incremento, nunca substituição (ex.: Pix.DevolucaoEnviada, Pix.DevolucaoRecebida).
Responder 2xx imediatamente após persistir; processar a lógica de negócio de forma assíncrona, fora do ciclo da requisição. Persistir cada entrega pelo EventId/Webhook-Id.
Responder 4xx (exceto 408/429) como falha permanente — a Pinbank não reenvia.
Responder 408, 429, 5xx ou timeout como falha temporária — esperar reentrega automática (janela de 24h).
