Autenticidade da mensagem

Toda entrega é assinada com Ed25519. Validar a assinatura garante que o callback foi emitido genuinamente pela Pinbank e que o payload não foi alterado em trânsito.

Obtendo a chave pública

GET /api/v1/signing/public-key

Endpoint público, sem autenticação. Resposta:

{
  "Algoritmo": "Ed25519",
  "ChavePublicaBase64": "MCowBQYDK2VwAyEA...",
  "ChavePublicaPem": "-----BEGIN PUBLIC KEY-----\nMCow...\n-----END PUBLIC KEY-----",
  "jwk": {
    "kty": "OKP", "crv": "Ed25519", "kid": "2026-07", "use": "sig", "x": "..."
  },
  "jwks": {
    "keys": [
      { "kty": "OKP", "crv": "Ed25519", "kid": "2026-07", "use": "sig", "x": "..." },
      { "kty": "OKP", "crv": "Ed25519", "kid": "2026-04", "use": "sig", "x": "..." }
    ]
  }
}

ChavePublicaBase64/ChavePublicaPem/jwk referem-se sempre à chave ativa (a que assina as entregas atuais).

jwks.keys contém a chave ativa e chaves anteriores ainda válidas para verificação — necessário durante uma rotação de chaves, quando entregas antigas (assinadas com a chave anterior) e novas podem coexistir na fila de retentativas.

Salve a resposta na sua aplicação; consulte o endpoint apenas na inicialização ou quando uma verificação falhar inesperadamente (pode indicar rotação de chave).

Selecionando a chave correta com `Webhook-Key-Id`

O header Webhook-Key-Id de cada entrega informa qual kid assinou aquele evento específico. Procure em jwks.keys a entrada cujo kid corresponda para obter a chave pública correta:

kid = headers["Webhook-Key-Id"]
public_key = entrada de jwks.keys onde entry.kid == kid

Isso garante que a verificação continue funcionando durante uma rotação de chaves. Em produção, prefira sempre selecionar a chave por kid em jwks.keys em vez de usar a chave ativa diretamente.

Como a assinatura é construída

O conteúdo assinado é a concatenação do timestamp com o body da requisição, separados por ponto:

{Webhook-Timestamp}.{body}

Exemplo:

1749772800.{"EventType":"Pix.CreditoRecebido","EventVersion":"v1","EventId":"550e8400-...","EntityId":"123456","OccurredAt":"2026-06-30T12:00:01Z","Data":{...}}

O header Webhook-Signature contém o prefixo v1a, seguido da assinatura em Base64:

Webhook-Signature: v1a,MEcCIGY3...==

Passos para verificar

Extraia os valores dos headers Webhook-Timestamp, Webhook-Signature e Webhook-Key-Id.

Verifique a frescura: rejeite requisições com timestamp fora da janela de ±5 minutos para prevenir ataques de replay.

Localize em jwks.keys a chave pública cujo kid corresponda a Webhook-Key-Id.

Extraia a assinatura do header Webhook-Signature, removendo o prefixo v1a,.

Reconstrua o conteúdo assinado: {timestamp}.{body} — use o body exatamente como recebido, sem reserializar.

Verifique a assinatura Ed25519 com a chave pública localizada no passo 3.

Atenção: use o body bruto da requisição HTTP, antes de qualquer parsing JSON. Reserializar o objeto pode alterar a formatação (ordem de campos, espaços) e invalidar a verificação.

Exemplos de implementação

Python (biblioteca cryptography):

Node.js:

Go:

Java:

Obtendo a chave pública#

Selecionando a chave correta com Webhook-Key-Id#

Como a assinatura é construída#

Passos para verificar#

Exemplos de implementação#

Obtendo a chave pública

Selecionando a chave correta com `Webhook-Key-Id`

Como a assinatura é construída

Passos para verificar

Exemplos de implementação