Webhooks no sandbox
Nesta página
Prove que a URL é suaEndereços que dispensam a provaConsulte a verificaçãoRepita a verificaçãoReceba no seu endpoint os avisos das transações de teste depois de provar que a URL é sua.
Prove que a URL é sua
O sandbox testa a URL ao cadastrar um webhook em POST /user/webhooks e a cada troca da url em PATCH /user/webhooks/{id}. Até a prova passar, o webhook não recebe nenhuma entrega.
| Quem | O que faz |
|---|---|
| Sandbox | Envia um POST para a URL com corpo {} e um valor no cabeçalho X-Callback-Challenge. |
| Seu endpoint | Responde em até 5 segundos com status 2xx e esse valor no corpo, puro ou em {"challenge":"…"}. |
import http from 'node:http'
http.createServer((req, res) => {
const challenge = req.headers['x-callback-challenge']
if (challenge) {
res.writeHead(200, { 'Content-Type': 'application/json' })
res.end(JSON.stringify({ challenge }))
return
}
// Aviso comum: confira a assinatura, grave e responda 2xx.
res.writeHead(200).end()
}).listen(3000)Como o corpo do POST é {}, um serviço que só repete o corpo recebido não passa na prova.
Endereços que dispensam a prova
Coletores públicos de teste recebem as entregas sem a prova, como webhook.site, webhook.cool, smee.io, postb.in, play.svix.com, free.beeceptor.com e console.hookdeck.com, com os seus subdomínios.
Para qualquer destino, o sandbox só entrega em HTTPS, para endereço público, e não segue redirecionamento.
URL em http | O que acontece |
|---|---|
| No webhook | O cadastro é recusado com 400. |
No callbackUrl de uma transação | A transação é criada e o aviso não é entregue. O callbackUrl não passa pela prova, mas segue as mesmas regras de endereço. |
Consulte a verificação
GET /sandbox/webhooks/{id}/challenge mostra o estado da prova em status: pending, verified ou failed. Em detail vem o motivo da última tentativa. A rota fica fora de /v1 e usa o mesmo token.
curl https://pix.sandbox.payzu.dev/sandbox/webhooks/WHK20260810K4M8Q2X7NB123456/challenge \
-H "Authorization: Bearer SEU_TOKEN"{
"webhookId": "WHK20260810K4M8Q2X7NB123456",
"url": "https://sualoja.com.br/webhook",
"status": "failed",
"detail": "o endpoint respondeu 2xx sem ecoar o token, no corpo ou em {\"challenge\"}",
"checkedAt": "2026-08-10T12:00:05.000Z"
}Repita a verificação
Depois de corrigir o endpoint, chame a mesma rota com POST. O sandbox faz a prova de novo na hora e retorna o resultado no mesmo formato da consulta.
curl -X POST https://pix.sandbox.payzu.dev/sandbox/webhooks/WHK20260810K4M8Q2X7NB123456/challenge \
-H "Authorization: Bearer SEU_TOKEN"Em produção, o webhook recebe as entregas assim que é cadastrado.
O formato de cada aviso, a assinatura e as retentativas são os mesmos nos dois ambientes; veja Webhooks e callbacks.