---
type: reference
title: Referência do payload de webhook
summary: A requisição exata que um webhook de verificação hospedada recebe, cada campo no corpo, e os cabeçalhos que o Caputchin envia.
---

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](/docs/hosted-verification/set-up); para o conceito, veja [verificar sem um backend](/docs/hosted-verification/overview).

## 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):

```json
{
  "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](/docs/hosted-verification/statistics).

## Veja também

- [Configurar a verificação hospedada](/docs/hosted-verification/set-up): conectar um webhook e disparar uma entrega de teste.
- [Verificar sem um backend](/docs/hosted-verification/overview): o conceito, a postura de privacidade e as regras de segurança de URL.
- [Estatísticas de verificação hospedada](/docs/hosted-verification/statistics): ler o sucesso e a falha de entrega.