> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ar-online.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba notificações automáticas a cada mudança de status, sem polling.

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.

<Tip>
  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](/referencia/rate-limit) para entender por que evitar polling é importante.
</Tip>

## Setup

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

<Note>
  Para ativar webhooks, comunique ao suporte ([suporte@ar-online.com.br](mailto: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.
</Note>

## 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:

```json theme={null}
{
  "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"
}
```

<CodeGroup>
  ```json Sucesso theme={null}
  {
    "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"
  }
  ```

  ```json Falha theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

### Payload v2

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

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

<ResponseField name="eventVersion" type="string">
  Versão do evento disparado.
</ResponseField>

<ResponseField name="occurredAt" type="string">
  Timestamp ISO 8601 do momento do evento.
</ResponseField>

<ResponseField name="notificationID" type="string">
  ID da notificação (equivale ao `idEmail` da API).
</ResponseField>

<ResponseField name="channel" type="string">
  Canal do evento (`email`, `sms`, `whatsapp`, `voz` ou `carta`).
</ResponseField>

<ResponseField name="status" type="string">
  Descrição do status atual.
</ResponseField>

<ResponseField name="statusTimestamp" type="string">
  Timestamp do status, quando disponível.
</ResponseField>

<ResponseField name="payload" type="object">
  Objeto com os dados do canal — mesma estrutura retornada pelo endpoint de consulta correspondente (ver tabela abaixo).
</ResponseField>

<ResponseField name="metadata.webhookVersion" type="string">
  Sempre `"v2"` nesta versão.
</ResponseField>

<ResponseField name="metadata.attempt" type="number">
  Número da tentativa de entrega (1 = primeira, até 4 com retentativas).
</ResponseField>

#### 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](/acompanhando/consultar-status) |
| `sms`      | [Consultar status](/acompanhando/consultar-status) |
| `whatsapp` | [Consultar status](/acompanhando/consultar-status) |
| `voz`      | [Consultar status](/acompanhando/consultar-status) |
| `carta`    | [Consultar status](/acompanhando/consultar-status) |

#### Exemplo

```json theme={null}
{
  "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](mailto: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:

<Steps>
  <Step title="Primeira tentativa">
    Após **15 minutos**.
  </Step>

  <Step title="Segunda tentativa">
    Após **1 hora**.
  </Step>

  <Step title="Terceira tentativa">
    Após **3 horas**.
  </Step>
</Steps>

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