Webhook de pagamento: seu sistema avisado no momento da aprovação
Eventos de venda, assinatura, recuperação e logística entregues no seu endpoint com assinatura HMAC SHA-256, retentativa automática e log de cada tentativa.
Sem mensalidade · Sem fidelidade · Cancele quando quiser
Checkout Voren
Pagamento 100% seguro
Liquidação D+0 · Split automático · Antifraude
SHA-256
Assinatura HMAC
18
Eventos disponíveis
HTTPS
Destino obrigatório
Auto
Retentativa de entrega
Onde webhook mal implementado machuca
O evento certo, aceito da forma errada, é um problema de segurança e de receita ao mesmo tempo.
Endpoint sem validação
Aceitar qualquer POST permite que alguém libere acesso pago com um payload inventado. Validar a assinatura é obrigatório, não opcional.
Handler não idempotente
Reentrega — normal em qualquer fila — vira acesso duplicado, comissão dobrada ou e-mail repetido.
Resposta lenta
Processar tudo dentro do request atrasa a resposta e joga a entrega para retentativa sem necessidade.
Confiar só no evento
Entrega perdida sem reconciliação por id deixa o seu banco divergente da cobrança para sempre.
Como a entrega funciona
Assinatura por secret
Cada webhook tem secret próprio; a assinatura cobre timestamp e corpo.
Seleção de eventos
Assine só o que interessa, ou tudo com o curinga *.
Log de tentativas
Status HTTP e resposta de cada entrega, para depurar sem adivinhar.
Destino protegido
Somente URLs HTTPS públicas; endereços internos são bloqueados.
Eventos de logística
order.shipped, order.delivered e order.returned para quem envia produto físico.
Eventos de recuperação
cart.abandoned, recovery.sent e recovery.recovered para automação de retomada.
Como implementar do jeito certo
- 1
1. Cadastre o endpoint
URL HTTPS e a lista de eventos que o seu sistema trata.
- 2
2. Dispare o test.ping
Confirme que o endpoint recebe e responde antes de ir para produção.
- 3
3. Leia o corpo bruto
Valide a assinatura sobre o body original, antes de qualquer parse mutável.
- 4
4. Compare o HMAC
Recalcule com o secret e descarte a entrega quando não bater.
- 5
5. Responda 2xx rápido
Enfileire o processamento e devolva a resposta imediatamente.
- 6
6. Reconcilie por id
Consulte /sales/{id} ou /subscriptions/{id} para resolver divergência.
Perguntas frequentes
Como valido que o webhook veio da Voren?
Cada entrega leva o header X-Voren-Signature com um HMAC SHA-256 calculado sobre a string `timestamp.body` usando o secret do seu webhook. Recalcule o mesmo HMAC no seu servidor a partir do corpo bruto da requisição e compare — se não bater, descarte.
Quais eventos posso ouvir?
Vendas: sale.pending, sale.paid, sale.failed, sale.canceled, sale.refunded e sale.chargeback. Assinaturas: subscription.created, subscription.updated, subscription.charged e subscription.canceled. Recuperação: cart.abandoned, recovery.sent e recovery.recovered. Logística: order.fulfillment_pending, order.shipped, order.delivered e order.returned. Além de test.ping para validar o endpoint.
Consigo assinar todos os eventos de uma vez?
Sim, cadastrando o curinga `*` na lista de eventos do webhook. Também é possível cadastrar vários webhooks, cada um ouvindo um subconjunto — por exemplo um endpoint só para logística e outro só para assinaturas.
E se o meu servidor estiver fora do ar?
A entrega é retentada e cada tentativa fica registrada com status HTTP e resposta, então você enxerga exatamente o que aconteceu. Mesmo assim, trate o webhook como aviso e reconcilie pelo endpoint de consulta quando precisar de certeza.
O webhook pode chegar duas vezes?
Pode, e é assim em qualquer sistema de entrega com retentativa. Torne o seu handler idempotente: use o identificador do evento ou da venda como chave e ignore o reprocessamento em vez de liberar acesso ou creditar duas vezes.
Preciso responder algo específico?
Responda 2xx rápido e faça o trabalho pesado em background. Resposta lenta ou erro leva a entrega para a fila de retentativa desnecessariamente.
A URL precisa ser HTTPS?
Sim. O destino precisa ser uma URL HTTPS pública e alcançável; endereços internos ou de rede privada são rejeitados por segurança.
Integre hoje, sem mensalidade
Crie a conta, gere as credenciais da API v1 e cobre pela sua própria aplicação. Você paga a taxa quando vende — e no Pix a taxa é 0% com liquidação em D+0.
Ver a documentação de webhooksLeva menos de 2 minutos · Não pedimos cartão
Continue explorando
Billing para SaaS
Cobrança de assinatura para produto digital.
Sistema de cobrança para SaaS
Planos, ciclos e inadimplência.
API de cobrança recorrente
Criar e gerir assinaturas via API v1.
Integrar pagamento no meu sistema
Do primeiro request ao primeiro pago.
API de pagamentos
Visão geral da API v1 da Voren.
Documentação da API
Referência dos endpoints.
Webhooks
Assinatura, retentativa e idempotência.
Cobrança recorrente
Como a renovação automática funciona.
MRR
Receita recorrente mensal na prática.
Dunning
Retentativa em D+1, D+3 e D+5.