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

# Webhooks

> Receba notificações em tempo real sobre eventos do sistema via webhooks.

> Webhooks permitem que sua aplicação receba notificações em tempo real quando eventos ocorrem na Aira — como mudanças de status em faturas.

## Como funciona

Quando um evento assinado ocorre, a Aira envia uma requisição `POST` para o endpoint configurado com os detalhes do evento. Sua aplicação processa a notificação e responde com um status `2XX` para confirmar o recebimento.

<br />

<h2 id="configuracao">
  Configuração
</h2>

Para receber webhooks, configure um endpoint no Dashboard:

1. Acesse **Configurações → Webhooks**
2. Informe a **URL** do seu endpoint
3. Selecione os **eventos** que deseja receber
4. Opcionalmente, defina um **token de autenticação** para validar as requisições

<br />

<h2 id="autenticacao">
  Autenticação
</h2>

Se um token for configurado, a Aira o envia no header `X-Webhook-Token` em toda requisição. Seu endpoint deve verificar o valor deste header antes de processar o payload.

```http theme={null}
POST /your-endpoint HTTP/1.1
Host: yourapp.com
Content-Type: application/json
X-Webhook-Token: seu_token_secreto

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "invoice.status-updated",
  "payload": { ... }
}
```

<br />

<h2 id="eventos-disponiveis">
  Eventos disponíveis
</h2>

| Evento                   | Descrição                                          |
| ------------------------ | -------------------------------------------------- |
| `invoice.status-updated` | Disparado quando o status de uma fatura é alterado |

<br />

<h2 id="estrutura-do-payload">
  Estrutura do payload
</h2>

Toda requisição de webhook segue esta estrutura:

```json theme={null}
{
  "id": "<UUID>",
  "event": "<EventType>",
  "payload": {
    // dados específicos do evento
  }
}
```

* **`id`** — identificador único do webhook
* **`event`** — tipo do evento (ex: `invoice.status-updated`)
* **`payload`** — dados específicos do evento

### invoice.status-updated

Disparado quando o status de uma fatura é alterado:

```json theme={null}
{
  "invoice": {
    "id": "<string>",
    "customer": {
      "id": "<string>",
      "name": "<string>",
      "externalId": "<string>"
    },
    "billingAccount": {
      "businessName": "<string>",
      "taxId": "<string>",
      "taxIdType": "<TaxIdType>"
    },
    "invoiceNumber": "<string>",
    "invoiceDate": "<string>",
    "dueDate": "<string | null>",
    "totalAmount": "<number>",
    "status": "<InvoiceStatus>"
  },
  "changes": {
    "oldStatus": "<InvoiceStatus>",
    "newStatus": "<InvoiceStatus>"
  }
}
```

**Valores de InvoiceStatus:** `open`, `in_review`, `issued`, `synced`, `pending`, `paid`, `overdue`, `canceled`, `failed`

<br />

<h2 id="retentativas">
  Retentativas
</h2>

Se o seu endpoint não responder com status `2XX`, a Aira tenta reenviar automaticamente até **3 vezes**. O código de resposta de cada tentativa é registrado para diagnóstico.

Webhooks que falharam após todas as tentativas podem ser **reprocessados manualmente** pelo Dashboard em **Configurações → Webhooks**.

<br />

<h2 id="verificacao-de-webhooks">
  Verificação de webhooks
</h2>

<Steps>
  <Step title="Verifique o header X-Webhook-Token">
    Compare o valor do header com o token que você configurou. Processe a requisição apenas se coincidirem.
  </Step>

  <Step title="Parse o payload JSON">
    Extraia os campos `event` e `payload` do corpo da requisição.
  </Step>

  <Step title="Processe o evento">
    Atualize seus sistemas conforme o tipo de evento recebido.
  </Step>

  <Step title="Responda com status 2XX">
    Confirme o recebimento para evitar retentativas automáticas.
  </Step>
</Steps>

<br />

<h2 id="proximos-passos">
  Próximos passos
</h2>

* [Autenticação](/api-reference/autenticacao) — configure sua chave de API
* [Respostas de erro](/api-reference/error-responses) — entenda o formato de erros