Saltar para o conteúdo principal
Um webhook é a Reval avisando o seu servidor de que algo aconteceu: um ciclo foi cobrado, uma cobrança falhou, um cliente pausou ou cancelou. É o complemento da API: a API você consulta, os webhooks avisam você. Tudo se configura em Reval → Integrações → Webhooks.
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

  1. Em Reval → Integrações → Webhooks, cole a URL do seu servidor (precisa ser https) e escolha a quais eventos ela assina.
  2. Salve. A Reval gera um segredo de assinatura (whsec_…) para esse endpoint: veja-o com «Mostrar» e copie para o seu servidor.
  3. Use «Enviar teste»: o seu endpoint recebe um evento test e o admin mostra o resultado (código HTTP ou erro).
Você pode ter até 10 endpoints por loja, cada um com a sua lista de eventos e o seu segredo. Pausar um endpoint para de enviar eventos sem apagar a configuração nem o histórico; Excluir remove os dois.
Os payloads incluem dados pessoais do assinante (email, nome, cidade). Por isso só se aceitam URLs https, e a Reval recusa endereços internos ou privados (localhost, IPs de rede local, hosts sem domínio). O nome é verificado de novo a cada envio, depois de resolver o DNS: se passar a apontar para um endereço privado, a entrega é descartada com 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. O topic de cada envio é subscription.<evento>, checkout.<evento> ou cart.<evento>:

O envio

Cada entrega é um POST 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.
Assine o corpo bruto exatamente como chegou (os bytes, não um JSON re-serializado), compare em tempo constante e rejeite assinaturas com mais de 5 minutos de diferença:
Se você acha que o segredo vazou, exclua o endpoint e crie outro: ele recebe um segredo novo. Os eventos que já estavam na fila do endpoint excluído são descartados.

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 URL https pública serve. Essas ferramentas costumam responder 2xx na hora, que é justamente o que a Reval espera.