Configure a verificação hospedada com uma caixa de entrada de teste

Ao final deste tutorial, você terá um formulário de contato funcionando cujos envios são verificados pelo Caputchin e entregues a um webhook, e terá visto um envio verificado cair em uma caixa de entrada de teste que você pode inspecionar. Usamos a webhook.site como destino primeiro, porque ela mostra o payload exato que o Caputchin envia antes de você se comprometer com o seu próprio endpoint.

Você precisa de um plano Alpha, Troop ou Apex (a verificação hospedada não está no Solo), de uma chave de site, e de uma página onde você possa editar o HTML do formulário. Se você ainda não adicionou o widget a uma página, adicione o widget primeiro; este tutorial assume um <caputchin-widget> funcionando.

1. Pegue uma caixa de entrada de teste

Abra a webhook.site em uma nova aba. Ela imediatamente te dá uma URL única que se parece com https://webhook.site/#!/<uuid>, e uma URL de entrega correspondente da forma https://webhook.site/<uuid>. Copie a URL de entrega (a sem o #!/). Deixe a aba aberta; toda requisição que ela recebe aparece ali em tempo real.

Esta URL é um substituto do seu webhook real. Trate-a como descartável, já que qualquer um com a URL pode ler o que chega.

2. Ligue a verificação hospedada

No painel, abra a chave de site e vá para a página Verificação hospedada dela.

1. Cole a URL de entrega da webhook.site no campo URL do webhook.
2. Deixe o e-mail vazio por enquanto.
3. Salve.

Você não precisa ligar o botão ativada ainda. O próximo passo usa Testar entrega, que funciona em um destino salvo esteja a verificação hospedada ligada ou não, então você pode confirmar a ligação antes de entrar no ar.

3. Envie uma entrega de teste

Na mesma página, use Testar entrega. O Caputchin envia um envio sintético direto ao seu destino sem rodar um jogo nem verificar um token, então é uma checagem pura da ligação do destino.

Mude para a aba da webhook.site. Um novo POST aparece em um ou dois segundos. Seu corpo JSON se parece com isto:

{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "test_...",
    "game_id": null,
    "score": null,
    "duration_ms": null,
    "verified_at": 1748640000000,
    "test": true
  },
  "form": {
    "email": "test@example.com",
    "message": "Test submission from your Caputchin dashboard."
  }
}

O marcador "test": true diz ao seu handler que isto foi um teste do painel, não um visitante real; ele está ausente em envios reais. Se você vê este payload, o destino funciona. Se nada chega, recheque que você copiou a URL de entrega (não a URL de visualização #!/) e a salvou.

4. Aponte seu formulário para o encaminhador

Agora faça um envio real passar pelo Caputchin. A única mudança no seu formulário é o action dele: em vez do seu próprio backend, ele posta na URL do encaminhador que a chave de site te mostra na página Verificação hospedada.

<form action="https://caputchin.com/api/forward/cpt_pub_..." method="POST">
  <input name="email" type="email" />
  <input name="message" />
  <caputchin-widget sitekey="cpt_pub_..."></caputchin-widget>
  <button type="submit">Send</button>
</form>

Nada mais muda. O widget ainda injeta o campo oculto caputchin-token quando o visitante resolve o desafio; o encaminhador lê esse campo, o verifica, e o remove antes de entregar o resto ao seu destino.

5. Ative a verificação hospedada

De volta à página Verificação hospedada, ligue o botão ativada e salve. O encaminhador rejeita envios para uma chave de site que não está ativada, então esse botão é o que torna o passo 4 ativo.

6. Envie o formulário de verdade

Carregue sua página, preencha o formulário, resolva o desafio e envie. Observe a aba da webhook.site: um segundo POST chega, desta vez sem o campo test e com metadados de verificação reais.

{
  "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!"
  }
}

Esse é o caminho inteiro: o visitante envia, o Caputchin verifica, seu destino recebe só o envio verificado. Um envio que falha na verificação (um token ausente, expirado ou reusado) nunca chega ao seu destino.

Trate o bloco caputchin do jeito que você trataria um veredito de backend: game_id, score e duration_ms são metadados alegados pelo cliente para as suas análises, não um sinal de confiança. A decisão de confiança é o fato de o envio ter chegado. Qualquer um desses três pode ser null em um envio real (por exemplo uma verificação sem jogo), então proteja contra null antes de lê-los.

7. Experimente o destino de e-mail também

A webhook.site também dá a cada caixa de entrada um endereço de e-mail, então você pode testar a entrega por e-mail do mesmo jeito. Na página da webhook.site, ache o endereço de e-mail único da sua caixa de entrada e copie-o; no momento em que isto é escrito ele se parece com <your-inbox-id>@emailhook.site, mas confira a página pela forma atual, já que a webhook.site é dona desse detalhe. Então:

1. De volta à página Verificação hospedada, cole esse endereço no campo e-mail.
2. Salve, e use Testar entrega de novo.

O e-mail chega na caixa de entrada da webhook.site ao lado das requisições: uma mensagem simples carregando os campos do formulário e um rodapé notando que o Caputchin verificou o envio. O e-mail é entregue pelo provedor de e-mail do Caputchin, então pode levar um pouco mais para cair do que um POST de webhook. Com uma URL de webhook e um endereço de e-mail definidos, um único envio se distribui para os dois, e conta como entregue se qualquer um deles der certo.

8. Coloque seu destino real

Quando a caixa de entrada de teste tiver mostrado o que esperar, substitua-a pela sua:

• Seu próprio webhook. Ponha a URL do seu endpoint no campo URL do webhook. Precisa ser uma URL https pública; o Caputchin recusa URLs que resolvem para endereços privados, de loopback ou de metadados de nuvem, e não vai seguir redirecionamentos. Seu handler recebe exatamente o formato JSON acima. As entregas não são assinadas, então mantenha a URL secreta, já que o segredo dela é o que autentica a chamada.
• E-mail em vez disso, ou também. Ponha o seu próprio endereço no campo e-mail, do mesmo jeito que você o testou acima. Você pode rodar os dois ao mesmo tempo, por exemplo um webhook para processamento mais uma cópia por e-mail para você.

Envie mais um envio real contra o destino ativo para confirmar, e então você terminou.

Para onde ir a seguir

• Estatísticas de verificação hospedada: acompanhe a saúde da entrega ao longo do tempo.
• Verificação hospedada: os conceitos, a postura de privacidade e o que é deixado de fora de propósito.
• Verificar no seu backend: a alternativa se você adicionar um servidor depois.