POST na URL do seu backend sempre que algo acontece: mensagem entregue, cliente respondeu, template aprovado, cobrança paga.
Receba seu primeiro evento
Você precisa de Node 18 ou mais novo e de acesso ao painel.1
Crie o receptor
Salve como
receptor.mjs. Ele lê o corpo bruto, confere a assinatura, responde 200 na hora e registra o evento.receptor.mjs
2
Exponha a porta local
A Arara precisa de um endereço Copie o endereço
https público. Em outro terminal, abra um túnel para a porta 3000:https://... que o túnel mostrar.3
Cadastre a URL e copie o secret
No painel, abra Webhooks:
- Em URL, cole o endereço do túnel seguido de
/webhooks/arara. - Gere o secret e copie o valor. Ele começa com
whsec_.
4
Rode o receptor
5
Dispare o evento de teste
Na mesma tela do painel, dispare o evento de teste. Em alguns segundos o terminal mostra:O
webhook.test não tem data.id nem data.status. Envie uma mensagem e você verá linhas como message.status_updated ara_msg_k9Bf2Xq delivered.A URL é uma por organização e só se configura pelo painel. Chave de API não dá acesso a essa configuração. O histórico de entregas, o reenvio e o evento de teste também ficam só no painel.
Verificar a assinatura
- Leia o corpo bruto, os bytes como chegaram, antes de qualquer parse.
- Calcule
HMAC-SHA256(secret, "{X-Arara-Timestamp}.{corpo bruto}")em hexadecimal. - Compare, em tempo constante, com o valor de
X-Arara-Signaturedepois desha256=. Recuse se o timestamp estiver a mais de 5 minutos do seu relógio.
Entrega
Responda com qualquer status2xx em até 5 segundos. Todo o resto conta como falha: outro status (inclusive 3xx, que não é seguido), timeout ou erro de conexão.
Cada entrega tem até 5 tentativas:
Depois da 5ª falha a entrega é marcada como falha definitiva e a organização recebe um alerta no painel. Você ainda pode reenviá-la pelo histórico de entregas.
Desativação automática
A Arara desativa o webhook quando as duas condições valem ao mesmo tempo: 50 falhas seguidas e 30 minutos falhando sem nenhuma entrega bem-sucedida. Uma entrega com sucesso zera a contagem.Deduplicação
Todas as tentativas e reenvios de uma entrega repetem o mesmoX-Arara-Delivery-Id. Grave esse valor com restrição de unicidade antes de processar e ignore os repetidos.
200 e não processe.
O mesmo fato também pode chegar em entregas diferentes, por exemplo dois message.status_updated com o mesmo status. Deixe o handler idempotente também pela chave de negócio, como data.id + data.status.
Ordem
A ordem não é garantida. Umdelivered pode chegar depois do read da mesma mensagem. Compare com o estado que você já tem e nunca regrida um status.
Processe em fila
Responda200 assim que a assinatura for válida e o X-Arara-Delivery-Id estiver gravado. O trabalho demorado (chamar outra API, enviar e-mail, atualizar pedido) vai para uma fila sua. Processar dentro da requisição estoura os 5 segundos e gera retentativa.
Testar localmente
Com a CLI
Oarara listen da CLI recebe os eventos da organização no terminal e encaminha cada um para o seu receptor local, sem túnel.
1
Autentique a CLI
2
Veja os eventos chegando
3
Encaminhe para o seu receptor
Com o Para receber o evento assinado, com o header
receptor.mjs rodando na porta 3000:X-Arara-Signature, use --capture:--capture, a assinatura é feita com o secret do listener temporário da CLI, não com o secret do painel. Para validar a verificação de assinatura de ponta a ponta com o secret de produção, use o túnel.
Com túnel
Qualquer túnel que entregue um endereçohttps público serve:
Headers enviados
Próximos passos
Eventos
Corpo e campos de cada evento.
Next.js
Route handler com verificação de assinatura.
Laravel
Controller com verificação de assinatura.
Por que minha mensagem falhou
O que cada motivo de falha significa.