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
- Pelo painel
- Pela API
- Abra Desenvolvedores → Webhooks.
- Clique em Adicionar destino e informe a URL (HTTPS).
- Escolha os eventos ou marque todos.
- Copie o segredo (
whsec_...) e guarde no seu servidor.
- 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 é umPOST 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.Responder
Responda com qualquer status2xx 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
Os eventos também podem chegar fora de ordem. Antes de agir, compare com ostatus 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}/deliverieslista as entregas, com filtro porstatus(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.