Pular para o conteúdo principal
O webhook é um POST que a Valora envia para uma URL sua sempre que algo acontece com um pagamento. É a forma certa de saber que um pagamento foi confirmado: não dependa só de consultar o status nem do retorno do cliente para a success_url.

Cadastrar um endpoint

  1. Abra Desenvolvedores → Webhooks.
  2. Clique em Adicionar destino e informe a URL (HTTPS).
  3. Escolha os eventos ou marque todos.
  4. Copie o segredo (whsec_...) e guarde no seu servidor.
O segredo aparece só na criação e na rotação. Se perder, rotacione com POST /v1/webhooks/{endpoint_id}/rotate_secret. Nunca coloque o segredo no código ou em logs.
Regras da URL:
  • Precisa ser https://, sem usuário e senha na URL.
  • Não pode apontar para a rede interna (localhost, IPs privados). Redirecionamentos não são seguidos.
  • Cada negócio pode ter até 10 endpoints ativos.

O que chega

Cada entrega é um POST com corpo JSON e estes headers:
data.object é o pagamento completo, no mesmo formato de GET /v1/payments/{payment_id}.

Verificar a assinatura

A assinatura prova que o evento veio da Valora e não foi alterado. Verifique antes de qualquer ação.
1

Leia o header

Separe t (horário do envio, em segundos Unix) e v1 (assinatura) de X-Valora-Signature.
2

Monte o texto assinado

Junte t, um ponto e o corpo cru da requisição: "<t>.<corpo>". Use os bytes exatos que chegaram, antes de qualquer parse do JSON.
3

Calcule e compare

Calcule o HMAC-SHA256 desse texto com o segredo do endpoint, em hexadecimal, e compare com v1 em tempo constante.
4

Confira o horário

Recuse eventos com t muito antigo (por exemplo, mais de 5 minutos). Isso impede que alguém reenvie um evento capturado.
No Express, use express.raw({ type: "application/json" }) na rota do webhook. No Next.js (App Router), leia com await request.text(). Os dois entregam o corpo cru.

Responder

Responda com qualquer status 2xx em até 10 segundos. Se o seu processamento demora, grave o evento numa fila, responda 200 e processe depois. Qualquer outra resposta (status fora de 2xx, tempo esgotado, erro de conexão) conta como falha.

Novas tentativas

Quando a entrega falha, a Valora tenta de novo, com intervalos crescentes. São até 8 tentativas no total: Depois da última, a entrega fica failed. Você pode reenviar pelo painel ou com POST /v1/webhooks/{endpoint_id}/deliveries/{delivery_id}/resend.

Eventos repetidos e fora de ordem

O mesmo evento pode chegar mais de uma vez (por exemplo, quando a sua resposta se perde na rede). Guarde o id do evento (evt_...) e ignore os que já processou.
Os eventos também podem chegar fora de ordem. Antes de agir, compare com o status atual do pagamento, que vem no próprio evento, ou consulte GET /v1/payments/{payment_id}.

Acompanhar as entregas

  • No painel: Desenvolvedores → Webhooks mostra cada entrega, o status HTTP que o seu servidor respondeu e o erro.
  • Pela API: GET /v1/webhooks/{endpoint_id}/deliveries lista as entregas, com filtro por status (pending, processing, delivered, failed).

Boas práticas

  • Verifique sempre a assinatura e o horário t.
  • Separe teste de produção pelo campo livemode: cada endpoint recebe eventos dos dois ambientes.
  • Seja idempotente: processe cada evt_... uma vez só.
  • Responda rápido e processe em segundo plano.
  • Rotacione o segredo se ele vazar.

Páginas relacionadas

Catálogo de eventos

Todos os eventos e quando cada um chega.

Testes

Teste o seu endpoint antes de produção.