1. Prepare o destino
Entre em Área do cliente com a API key entregue pelo administrador. Cadastre uma URL HTTPS com certificado válido, porta 443 e IPv4 público. Guarde o segredo de assinatura exibido uma única vez. Novas cobranças usam esse destino automaticamente.
2. Associe a cobrança
GET /api/pix/SUA_API_KEY/50.00 GET /api/status/SUA_API_KEY/ID_DA_COBRANCA
Informe a API key e o valor diretamente no caminho. O webhook vem do cadastro. external_reference e idempotency_key são opcionais. Na geração, valores são em reais: 50.00 = R$ 50,00. Nas respostas e nos webhooks, continuam em centavos. Salve o ID retornado e a chave de idempotência no pedido.
3. Confira a assinatura antes de processar
X-PixControl-Event-Id: UUID_DO_EVENTO X-PixControl-Timestamp: SEGUNDOS_UNIX X-PixControl-Signature: sha256=HMAC_HEXADECIMAL HMAC-SHA256(segredo, timestamp + "." + corpo_cru)
Use o segredo como texto UTF-8. Valide o corpo original, compare em tempo constante e rejeite timestamps fora de ±5 minutos. Depois confira que o ID do cabeçalho é igual ao ID do evento.
4. Processe de forma idempotente
{
"id": "UUID_DO_EVENTO",
"event": "charge.paid",
"api_version": "1",
"created_at": "2026-10-13T20:00:00.000Z",
"data": {
"id": "UUID_DA_COBRANCA",
"external_reference": "pedido-123",
"kind": "charge",
"amount": 5000,
"currency": "BRL",
"status": "paid",
"paid": true,
"status_version": 2,
"needs_review": false,
"status_url": "https://seu-gateway.com/api/v1/pix/ID"
}
}Confira ID da operação, referência e valor esperado. Persista o ID do evento e o efeito no pedido na mesma transação. Ignore versões antigas. Responda 2xx após gravar, deixando a entrega do produto para seu worker. Apenas charge.paid / paid=true libera o pedido.
Para consultar status, use /api/status/SUA_API_KEY/ID_DA_COBRANCA, com o ID recebido no evento. A rota lê somente o banco local. Trocas de URL afetam novas cobranças; pause o destino antigo para suspender suas entregas.
Falhas, disputas e testes
O mesmo evento pode chegar novamente ou fora de ordem. Há 12 tentativas por ciclo com intervalos crescentes; esgotados ficam no painel para reenvio. webhook.test não representa pagamento. charge.infraction, charge.med e charge.returned exigem acompanhamento posterior. Eventos de saque usam prefixo withdrawal., mas status no corpo é PENDING, PROCESSING, COMPLETED ou CANCELED.
O pacote entregue contém o guia completo docs/WEBHOOKS.md, exemplo opcional de receptor para o backend do cliente, com deduplicação em banco em examples/client-webhook-receiver.js e schema examples/client-webhook-receiver.sql.