Recebendo eventos das suas vendas

Além de receber você pode enviar: a IuzyPay avisa os seus sistemas sempre que algo importante acontece numa venda. São os webhooks de saída.

Não confunda com o webhook da Pagar.me, que é o gateway avisando a IuzyPay. Aqui é o contrário: a IuzyPay avisa você.

Eventos disponíveis

• Pedido pago (order.paid) — hora de liberar a entrega.
• Pedido reembolsado (order.refunded).
• Pedido expirado (order.expired) — Pix não pago no prazo.
• Chargeback (order.chargeback) — o comprador contestou a cobrança.
• Checkout abandonado (cart.abandoned) — lead que iniciou e não concluiu.
• Assinatura criada (subscription.created) — primeira cobrança de uma recorrência foi aprovada.
• Assinatura renovada (subscription.renewed) — um novo ciclo foi cobrado com sucesso.
• Assinatura em atraso (subscription.past_due) — a cobrança de renovação falhou e entrou em cobrança.
• Assinatura cancelada (subscription.canceled).

Cadastrando um endpoint

1. Vá em Configurações → Webhooks.
2. Informe a URL que vai receber os eventos e selecione quais deseja.
3. Ao salvar, copie o secret de assinatura — ele é exibido uma única vez.

Validando a autenticidade

Cada entrega vai assinada: um HMAC-SHA256 do corpo, usando o seu secret, no cabeçalho X-Iuzy-Signature. No seu servidor, recalcule a assinatura com o secret e compare — se bater, o evento é legítimo e não foi adulterado.

Confiabilidade

• Se o seu endpoint falhar, a IuzyPay repete a entrega algumas vezes, com intervalos crescentes.
• O painel guarda um histórico das últimas entregas (com número de tentativas), útil para depurar.
• Use o botão Testar para disparar um evento de exemplo e conferir que sua integração recebe e valida corretamente.

Trate a entrega como gatilho, não como verdade final: ao receber order.paid, o ideal é o seu sistema seguir seu próprio fluxo de liberação. Reentregas podem repetir um evento — projete o recebimento para ser idempotente.