Os webhooks são best-effort em relação ao fluxo principal: um endpoint fora do ar nunca segura uma cobrança nem a criação de um pedido. A Reval enfileira o envio, tenta à parte e tenta de novo se falhar.
Configurar um endpoint
- Em Reval → Integrações → Webhooks, cole a URL do seu servidor (precisa ser
https) e escolha a quais eventos ela assina. - Salve. A Reval gera um segredo de assinatura (
whsec_…) para esse endpoint: veja-o com «Mostrar» e copie para o seu servidor. - Use «Enviar teste»: o seu endpoint recebe um evento
teste o admin mostra o resultado (código HTTP ou erro).
Os eventos
São os mesmos 15 eventos de assinatura que a Reval envia ao Klaviyo e ao Shopify Flow, com os mesmos dados, mais os 3 de checkouts e carrinhos abandonados, que ainda não têm assinatura e saem só para o Klaviyo e para webhooks. Otopic de cada envio é subscription.<evento>, checkout.<evento> ou cart.<evento>:
O envio
Cada entrega é umPOST para a sua URL com um corpo JSON e estes headers:
data traz as mesmas propriedades que o Klaviyo e o Shopify Flow recebem: identidade do cliente, produto, valores (brutos e formatados), plano, número do ciclo, datas, endereço de entrega e links para o portal, além das propriedades próprias de cada evento (reason, source, detail, held_product_names, merged_with_subscription_ids etc.).
As propriedades de data
As propriedades são as mesmas para todos os eventos, mais as próprias de cada um. Vão em snake_case; os valores brutos são números e os _formatted são strings prontas para um email. Os rótulos (frequency_label, next_payment_date_label, reason, reason_text) seguem o idioma configurado da loja (espanhol ou português); para condições use as propriedades brutas (status, frequency_type, source, datas ISO) e reason_key, que não mudam com o idioma.
E, além disso, conforme o evento:
Responda qualquer 2xx o quanto antes — de preferência antes de processar — e processe em segundo plano. A Reval espera 10 segundos; depois desiste e conta a tentativa como falha. Redirecionamentos não são seguidos.
Verificar a assinatura
Cada envio vai assinado com o segredo do endpoint para você confirmar que foi a Reval que enviou e que nada foi alterado:té a hora do envio em segundos Unix.v1éHMAC-SHA256(segredo, "<t>.<corpo bruto>")em hexadecimal.
Novas tentativas
Se o seu servidor responder algo que não seja 2xx, não responder em 10 segundos ou não puder ser resolvido, a Reval tenta de novo com espera crescente:
Depois da sétima tentativa a entrega fica Falhou. Ela não se perde: você a vê no registro e pode reenviar quando o seu servidor voltar.
Como as novas tentativas mantêm o mesmo
X-Reval-Delivery, um endpoint que respondeu 2xx tarde (logo depois do timeout, por exemplo) pode receber o mesmo evento duas vezes. Guarde o ID e descarte os repetidos.
Registro de entregas
Em cada endpoint, «Ver entregas» mostra as últimas 50: evento, data, quantidade de tentativas, status (Pendente, Em andamento, Entregue, Falhou), código HTTP da última resposta e o erro, se houver. Cada linha tem «Reenviar», que manda exatamente o mesmo payload com o mesmo ID.Perguntas frequentes
Eventos anteriores à criação do endpoint são enviados? Não. Um endpoint recebe os eventos que acontecem enquanto ele existe e está ativo. Para o histórico existe a API. Posso receber só cancelamentos? Sim: ao criar ou editar o endpoint, marque só os eventos que interessam. O que acontece se eu pausar o endpoint? Os eventos que ocorrerem enquanto ele estiver pausado não são enviados nem guardados para ele. Ao retomar, ele recebe os novos. Meu endpoint pode estar no Zapier, Make ou n8n? Sim, qualquer URLhttps pública serve. Essas ferramentas costumam responder 2xx na hora, que é justamente o que a Reval espera.