> For the complete documentation index, see [llms.txt](https://digitalsac.gitbook.io/digicalls/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://digitalsac.gitbook.io/digicalls/webhook/webhook-de-integracao-cliente.md).

# Webhook de integração (cliente)

Envia eventos do DigiCalls para um **endpoint HTTP seu** (CRM, ERP, Izing backend).

### Configurar

#### Painel (device QR pareado)

**Dispositivos → abrir linha → Webhook de integração**

* URL do endpoint (HTTPS recomendado)
* Secret opcional (HMAC)
* Ativar/desativar

#### API (provisionamento)

```http
GET /api/devices/{token}/webhook
X-Api-Key: dgu_...

PUT /api/devices/{token}/webhook
Content-Type: application/json

{
  "enabled": true,
  "url": "https://seu-crm.com/hooks/digicalls",
  "secret": "segredo-compartilhado",
  "events_call": true,
  "events_record": true,
  "events_device": true
}
```

#### API (sessão logada)

```http
GET  /api/sessions/{sid}/webhook
PUT  /api/sessions/{sid}/webhook
Authorization: Bearer <login>
```

### Autenticação do POST

Se `secret` estiver definido, cada request inclui:

```
X-DigiCalls-Signature: sha256=<hmac-sha256 do body>
```

### Eventos

#### CALL

Disparado em criação/atualização de chamada.

```json
{
  "type": "CALL",
  "action": "CREATE",
  "session_id": "...",
  "device_token": "dev_...",
  "call_id": "...",
  "caller": "5511...",
  "receiver": "",
  "status": "INCOMING_RING",
  "direction": "INCOMING",
  "duration": 0,
  "record_status": "DISABLED"
}
```

`action`: `CREATE` | `UPDATE`

Status comuns: `INCOMING_RING`, `OUTGOING_RING`, `ACTIVE`, `ENDED`

#### RECORD

Quando a gravação fica disponível:

```json
{
  "type": "RECORD",
  "action": "UPDATE",
  "session_id": "...",
  "call_id": "...",
  "record_status": "READY",
  "record_url": "https://calls.digitalsac.io/api/recordings/..."
}
```

Baixe com `GET record_url` usando `X-Api-Key`.

#### DEVICE

Mudança de pareamento/conexão:

```json
{
  "type": "DEVICE",
  "action": "UPDATE",
  "session_id": "...",
  "device_token": "dev_...",
  "status": "open",
  "paired": true,
  "phone": ""
}
```

### Retry

O dispatch é **best-effort** (uma tentativa, timeout 12s). Para garantia, combine com polling `GET /api/devices/{token}/calls` ou SSE.

### vs. Webhook Meta

|         | Integração cliente       | Meta WABA           |
| ------- | ------------------------ | ------------------- |
| Direção | DigiCalls → seu servidor | Meta → DigiCalls    |
| Config  | Por device               | Por conexão oficial |
| Doc     | Esta página              | Webhook Meta (WABA) |