Webhooks

Webhooks permitem que a AR Online avise a sua aplicação, de forma assíncrona, sempre que o status de uma notificação muda. Em vez de consultar repetidamente os endpoints de status, você recebe uma chamada POST no seu endpoint a cada atualização.

Por que usar webhooks

Webhooks eliminam a necessidade de polling recorrente aos endpoints de consulta de status. Em vez de a sua aplicação ficar perguntando ativamente “já mudou?”, ela recebe a notificação no momento em que a mudança acontece.

Além de simplificar a sua integração, webhooks reduzem o consumo de requisições e o risco de bloqueio por excesso de chamadas. Consulte a política de Rate Limit para entender por que evitar polling é importante.

Setup

A configuração de webhooks é feita junto à nossa equipe de atendimento.

Para ativar webhooks, comunique ao suporte (suporte@ar-online.com.br):

O endpoint que receberá as notificações.
Os parâmetros de autenticação fixos, enviados por nós no campo Authorization do cabeçalho da requisição.

Requisitos do seu endpoint:

Aceitar requisições POST.
Retornar sempre um status 2xx em caso de recebimento bem-sucedido.

Gatilhos que iniciam o fluxo

Qualquer alteração no status do e-mail (ou da notificação em outros canais) aciona a chamada para o endpoint previamente configurado com a nossa equipe de atendimento.

Payloads

Existem duas versões de payload. A v1 é entregue por padrão; a v2 é uma estrutura enriquecida, ativada mediante solicitação ao suporte.

Payload v1

Estrutura entregue por padrão:

{
  "notificationID": "ID da Notificação",
  "channel": "Canal do Status",
  "description": "Descrição do Status",
  "dateSent": "Data do envio",
  "dateDelivery": "Data da entrega",
  "dateRead": "Data da leitura",
  "logDate": "Data do Log"
}

{
  "notificationID": "65c863ee-a186-40c4-b659-b48cad543bd0",
  "channel": "email",
  "description": "Lido",
  "dateSent": "26/07/2023 13:34:23",
  "dateDelivery": "26/07/2023 13:34:28",
  "dateRead": "26/07/2023 13:34:50",
  "logDate": "31/08/2023 14:17:13"
}

{
  "notificationID": "71789707-0301-429d-8932-6834f6602f10",
  "channel": "email",
  "description": "Falha no Envio/Entrega",
  "dateSent": null,
  "dateDelivery": null,
  "dateRead": null,
  "logDate": "31/08/2023 14:15:58"
}

Payload v2

Versão enriquecida do payload, com estrutura alinhada às respostas dos endpoints de consulta da API Gateway por canal.

Estrutura

{
  "eventVersion": "string",
  "occurredAt": "string",
  "notificationID": "string",
  "channel": "email | sms | whatsapp | voz | carta",
  "status": "string",
  "statusTimestamp": "string (opcional)",
  "payload": {},
  "metadata": {
    "webhookVersion": "v2",
    "attempt": 1
  }
}

string

Versão do evento disparado.

string

Timestamp ISO 8601 do momento do evento.

string

ID da notificação (equivale ao idEmail da API).

string

Canal do evento (email, sms, whatsapp, voz ou carta).

string

Descrição do status atual.

string

Timestamp do status, quando disponível.

object

Objeto com os dados do canal — mesma estrutura retornada pelo endpoint de consulta correspondente (ver tabela abaixo).

string

Sempre "v2" nesta versão.

number

Número da tentativa de entrega (1 = primeira, até 4 com retentativas).

Referência do campo `payload` por canal

O conteúdo de payload espelha a resposta do endpoint GET de consulta de status do respectivo canal:

Canal	Endpoint de referência
`email`	Consultar status
`sms`	Consultar status
`whatsapp`	Consultar status
`voz`	Consultar status
`carta`	Consultar status

Exemplo

{
  "eventVersion": "2",
  "occurredAt": "2026-05-06T06:09:05.303Z",
  "notificationID": "3dad7f95-f1e9-4924-8154-f5e97e8ebe42",
  "channel": "email",
  "status": "Processado",
  "payload": {
    "dateSend": "",
    "dateDelivery": "",
    "dateReading": null,
    "dateAcceptance": null,
    "error": false,
    "description": "Processado",
    "failureReason": null,
    "customID": "2",
    "idEmail": "3dad7f95-f1e9-4924-8154-f5e97e8ebe42"
  },
  "metadata": {
    "webhookVersion": "v2",
    "attempt": 0
  }
}

Compatibilidade de versões

A v1 do payload permanece em funcionamento e continuará sendo entregue por padrão. Clientes que desejarem migrar para a v2 podem solicitar a ativação ao time de suporte: suporte@ar-online.com.br.

Fluxo de tentativas

A aplicação realiza uma chamada POST com timeout de até 15 segundos. Em caso de falha na resposta — indicada por qualquer código diferente de 2xx — o sistema realiza até três tentativas subsequentes, nos seguintes intervalos:

Primeira tentativa

Após 15 minutos.

Segunda tentativa

Após 1 hora.

Terceira tentativa

Após 3 horas.

Após o término das três tentativas, o sistema encerra o fluxo de entrega.

Início

Enviando notificações

Acompanhando envios

Notas técnicas

Templates

Referência da API

Endpoints

Webhooks

Por que usar webhooks

Setup

Gatilhos que iniciam o fluxo

Payloads

Payload v1

Payload v2

Referência do campo `payload` por canal

Exemplo

Compatibilidade de versões

Fluxo de tentativas

​Por que usar webhooks

​Setup

​Gatilhos que iniciam o fluxo

​Payloads

​Payload v1

​Payload v2

​Referência do campo payload por canal

​Exemplo

​Compatibilidade de versões

​Fluxo de tentativas

Por que usar webhooks

Setup

Gatilhos que iniciam o fluxo

Payloads

Payload v1

Payload v2

Referência do campo `payload` por canal

Exemplo

Compatibilidade de versões

Fluxo de tentativas