PayZu Pix

Webhooks no sandbox


Nesta páginaProve que a URL é suaEndereços que dispensam a provaConsulte a verificaçãoRepita a verificação

Receba 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.

QuemO que faz
SandboxEnvia um POST para a URL com corpo {} e um valor no cabeçalho X-Callback-Challenge.
Seu endpointResponde em até 5 segundos com status 2xx e esse valor no corpo, puro ou em {"challenge":"…"}.
responder-desafio.js
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 httpO que acontece
No webhookO cadastro é recusado com 400.
No callbackUrl de uma transaçãoA 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.

bash
curl https://pix.sandbox.payzu.dev/sandbox/webhooks/WHK20260810K4M8Q2X7NB123456/challenge \
  -H "Authorization: Bearer SEU_TOKEN"

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.

bash
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.