Webhook

Por que usar Webhooks?

Webhooks eliminam a necessidade de polling recorrente aos endpoints de status, o que é especialmente importante sob a política de Rate Limit da plataforma. Em vez de consultar ativamente, sua aplicação recebe notificações de forma assíncrona a cada mudança de status — reduzindo consumo de requisições e risco de bloqueio por excesso de chamadas.

Setup

Para utilizar esta solução, é importante comunicar à nossa equipe de atendimento o seu interesse, bem como o endpoint destinado a receber as respostas geradas pela nossa aplicação. Nossas chamadas de aplicação são compatíveis com autenticação por meio de parâmetros fixos no campo 'Authorization' do cabeçalho. A chamada sempre será um POST e o endpoint invocado deverá sempre retornar um status 2xx.

Gatilhos que iniciam o fluxo

Qualquer alteração no status do e-mail acionará a chamada para o endpoint previamente configurado com nossa equipe de atendimento.

Retornos

Payload de retorno

{
  "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"
}

Exemplo de Sucesso

{
  "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"
}

Exemplo de Falha

{
  "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"
}

Compatibilidade de Versões

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

Versão 2 do 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
  }
}

Onde:

• eventVersion: versão do evento disparado
• occurredAt: timestamp ISO 8601 do momento do evento
• notificationID: ID da notificação (equivale ao idEmail da API)
• channel: canal do evento
• status: descrição do status atual
• statusTimestamp: timestamp do status, quando disponível
• payload: objeto com os dados do canal — mesma estrutura retornada pelo endpoint de consulta correspondente (ver referências abaixo)
• metadata.webhookVersion: sempre "v2" nesta versão
• metadata.attempt: 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 do respectivo canal:

Canal	Endpoint de referência
email	Consulta do status do AR-Email
sms	Consulta do status do AR-SMS
whatsapp	Consulta do status do AR-Whatsapp
voz	Consulta do status do AR-Voz
carta	Consulta do status do AR-Cartas

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
  }
}

Fluxo de tentativas

A aplicação realizará uma chamada POST com um timeout configurado de até 15 segundos. Em caso de falha na resposta, indicada por qualquer código de status diferente de 2xx, o sistema realizará até três tentativas subsequentes, seguindo os intervalos detalhados abaixo:

• 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 encerrará o fluxo de entrega.