Referência do payload de webhook

Quando um envio passa na verificação, o encaminhador envia um POST para a URL de webhook que você configurou. Esta página é o contrato exato dessa requisição. Para o passo a passo de configuração, veja configurar a verificação hospedada; para o conceito, veja verificar sem um backend.

Linha de requisição e cabeçalhos

O encaminhador envia um POST com um corpo JSON e estes cabeçalhos:

Cabeçalho	Valor
`content-type`	`application/json`
`accept`	`application/json`
`user-agent`	`Caputchin-Forwarder/0.1`
`x-caputchin-test`	`1`, presente só em uma Entrega de teste do painel; ausente em envios reais

A chamada é enviada com redirecionamentos desabilitados e um timeout de alguns segundos. A requisição não é assinada; o segredo da URL do webhook é o que a autentica.

Corpo

O corpo é um objeto JSON com duas chaves de nível superior, caputchin (metadados de verificação que o Caputchin adiciona) e form (os campos que você enviou):

{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "...",
    "game_id": "caputchin/games/leaf-memory",
    "score": 847,
    "duration_ms": 4200,
    "verified_at": 1748640000000
  },
  "form": {
    "email": "visitor@example.com",
    "message": "Hello!"
  }
}

O objeto `caputchin`

Campo	Tipo	Significado
`site_key`	string	A chave pública `cpt_pub_...` da qual o envio veio.
`session_id`	string	Um id de sessão de verificação opaco, útil para correlação ou deduplicação. Em uma entrega de teste ele tem o prefixo `test_`.
`game_id`	string ou null	O jogo que o visitante jogou. Null quando a verificação rodou sem um jogo.
`score`	number ou null	A pontuação do jogo. Metadado alegado pelo cliente para análises, nunca um sinal de confiança. Null quando não se aplica.
`duration_ms`	number ou null	Quanto o visitante passou jogando o jogo, em milissegundos. Alegado pelo cliente, não um sinal de confiança. Null quando não se aplica (por exemplo uma verificação sem jogo).
`verified_at`	number	Quando o Caputchin verificou o token, como um epoch Unix em milissegundos.
`test`	boolean (opcional)	Presente e `true` só em uma entrega de teste do painel. Ausente em envios reais.

game_id, score e duration_ms são cada um anuláveis em um envio real, então proteja contra null antes de lê-los. Nenhum dos campos de caputchin é uma decisão de confiança: a confiança é que a requisição chegou, porque um envio que falha na verificação nunca é encaminhado.

O objeto `form`

form é um objeto plano dos campos que você enviou, como chaves string e valores string, exatamente como postados, com uma mudança: o campo caputchin-token é removido antes da entrega, então nunca aparece aqui. O encaminhador aceita só campos de texto; um envio carregando um upload de arquivo é rejeitado antes de qualquer entrega.

O que seu handler deve retornar

Retorne qualquer status 2xx para confirmar o recebimento. O encaminhador trata uma resposta não 2xx, um timeout ou uma falha de conexão como uma entrega falha, e uma entrega falha não é repetida. Acompanhe a saúde da entrega na página de estatísticas.

Veja também

Configurar a verificação hospedada: conectar um webhook e disparar uma entrega de teste.
Verificar sem um backend: o conceito, a postura de privacidade e as regras de segurança de URL.
Estatísticas de verificação hospedada: ler o sucesso e a falha de entrega.