Skip to main content
A Arara faz um 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 https público. Em outro terminal, abra um túnel para a porta 3000:
Copie o endereço https://... que o túnel mostrar.
3

Cadastre a URL e copie o secret

No painel, abra Webhooks:
  1. Em URL, cole o endereço do túnel seguido de /webhooks/arara.
  2. Gere o secret e copie o valor. Ele começa com whsec_.
Faça isso antes de testar. Sem o secret, o receptor recusa todos os eventos.
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.
A lista de eventos e o formato do corpo estão em Eventos.

Verificar a assinatura

  1. Leia o corpo bruto, os bytes como chegaram, antes de qualquer parse.
  2. Calcule HMAC-SHA256(secret, "{X-Arara-Timestamp}.{corpo bruto}") em hexadecimal.
  3. Compare, em tempo constante, com o valor de X-Arara-Signature depois de sha256=. Recuse se o timestamp estiver a mais de 5 minutos do seu relógio.
Compare sempre em tempo constante (timingSafeEqual, hmac.compare_digest, hash_equals). Com ==, dá para descobrir a assinatura byte a byte medindo o tempo de resposta. Verifique a assinatura antes de gravar qualquer coisa.
Se você não definir um secret, a Arara gera um na primeira entrega. O painel mostra o secret atual.

Entrega

Responda com qualquer status 2xx 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.
Com o webhook desativado, os eventos novos não são guardados nem reenviados depois. Corrija o endpoint e reative pelo painel. Para saber o status de uma mensagem que você perdeu, consulte GET /v1/messages/{id}.

Deduplicação

Todas as tentativas e reenvios de uma entrega repetem o mesmo X-Arara-Delivery-Id. Grave esse valor com restrição de unicidade antes de processar e ignore os repetidos.
Sem linha retornada, é repetido: responda 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. Um delivered pode chegar depois do read da mesma mensagem. Compare com o estado que você já tem e nunca regrida um status.

Processe em fila

Responda 200 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

O arara 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

Para filtrar por tipo:
3

Encaminhe para o seu receptor

Com o receptor.mjs rodando na porta 3000:
Para receber o evento assinado, com o header X-Arara-Signature, use --capture:
Enquanto um arara listen --capture está ativo, os eventos da organização vão para a CLI em vez da URL cadastrada no painel. Não deixe a captura ligada numa organização em produção.
Com --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ço https público serve:
Cadastre o endereço gerado no painel, seguido do caminho do seu receptor, e dispare o evento de teste. O painel mostra, para cada entrega, o corpo enviado, os headers e a resposta do seu servidor.

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.