Use este guia para configurar webhooks e receber eventos da IAra em sistemas externos.

## O que são webhooks

Webhooks são chamadas HTTP enviadas pela IAra quando algo acontece na conta, como criação de mensagem, mudança de conversa ou evento operacional. Eles permitem integrar a IAra com CRMs, ERPs, automações, data warehouses e ferramentas internas.

## Criar webhook

1. Acesse **Configurações > Integrações > Webhooks**.
2. Clique em **Adicionar novo webhook**.
3. Informe a URL que receberá requisições `POST`.
4. Selecione os eventos que deseja assinar.
5. Salve e faça um teste controlado.

## Exemplo de payload

```json
{
  "event": "message_created",
  "id": "1",
  "content": "Olá",
  "created_at": "2026-06-01T13:05:57Z",
  "message_type": "incoming",
  "content_type": "text",
  "content_attributes": {},
  "source_id": "",
  "sender": {
    "id": "1",
    "name": "Maria Souza",
    "email": "maria@example.com"
  },
  "contact": {
    "id": "1",
    "name": "Maria Souza"
  },
  "conversation": {
    "display_id": "42",
    "status": "open",
    "inbox_id": "10"
  },
  "account": {
    "id": "59",
    "name": "Minha conta"
  }
}
```

## Eventos comuns

- `message_created`
- `message_updated`
- `conversation_created`
- `conversation_updated`
- `conversation_status_changed`
- `conversation_typing_on`
- `conversation_typing_off`

## Verificar assinatura do webhook

Quando disponível na conta, a IAra assina as requisições para que seu servidor confirme que o payload não foi adulterado.

Cabeçalhos esperados:

- `X-IAra-Signature`
- `X-IAra-Timestamp`
- `X-IAra-Delivery`

A assinatura segue o formato:

```text
sha256=HMAC-SHA256(webhook_secret, "{timestamp}.{raw_body}")
```

## Exemplo em Node.js

```js
const crypto = require('crypto');

function verifySignature(rawBody, timestamp, receivedSignature, secret) {
  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(`${timestamp}.${rawBody}`)
      .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSignature)
  );
}
```

## Boas práticas

- Responda rápido com status `2xx`.
- Processe tarefas demoradas em fila.
- Registre `event`, `id`, horário e payload bruto.
- Valide assinatura antes de confiar no payload.