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

# Eventos de webhooks

> Receba avisos sobre chamadas de voz em tempo real (voice.call.*).

<Tip>
  Na API você **pergunta**; no webhook a Notifique **avisa**. Ideal para URA, discador e billing por minuto, sem polling de status.
</Tip>

## Em poucas palavras

* Toda entrega é um **POST** `application/json` para a URL cadastrada.
* Chamadas usam **`voice.call.*`**, não confunda com `message.*` (WhatsApp) ou `sms.*`.
* Ciclo do **número contratado** (`phone_number.*`) está em [Números de telefone, Eventos](/phone-numbers-api/como-funciona/eventos-do-webhooks).
* `instanceId` vem **vazio** (voz não usa instância de canal).
* Responda **2xx rápido**; processamento pesado vai para fila no seu lado.

Configuração geral: [Webhooks](/guides/webhooks/index). Segurança (assinatura HMAC): [Segurança de webhooks](/guides/webhooks/seguranca).

***

## Como vem o POST

```json theme={null}
{
  "event": "voice.call.answered",
  "workspaceId": "clxx123...",
  "instanceId": "",
  "timestamp": "2026-06-11T14:30:00.000Z",
  "data": {
    "callId": "clxx_call_1",
    "direction": "OUTBOUND",
    "fromE164": "+5511987654321",
    "toE164": "+5511999887766",
    "status": "ANSWERED",
    "clientState": "campanha-42"
  }
}
```

| Campo         | Descrição                                      |
| ------------- | ---------------------------------------------- |
| `event`       | Nome do evento (ex.: `voice.call.answered`)    |
| `workspaceId` | ID do workspace                                |
| `instanceId`  | Sempre vazio em voz                            |
| `timestamp`   | ISO 8601, use para anti-replay                 |
| `data`        | Campos da chamada ou do número (**camelCase**) |

Headers: `X-Notifique-Signature`, `X-Notifique-Timestamp`, `X-Workspace-Id`, `X-Webhook-Event`.

***

## O que seu servidor deve responder

| Resposta                | Efeito                                      |
| ----------------------- | ------------------------------------------- |
| **2xx** em até \~10s    | Evento entregue; sai da fila                |
| **4xx / 5xx / timeout** | Retentativa automática (5 min, 30 min, 2 h) |

<Note>
  Processamento demorado? Responda **200** logo e processe em background.
</Note>

***

## Eventos de chamada (`voice.call.*`)

| Evento                        | Quando dispara                 | O que fazer com isso    |
| ----------------------------- | ------------------------------ | ----------------------- |
| `voice.call.initiated`        | Discagem de saída iniciada     | Log, CRM                |
| `voice.call.received`         | Chamada **entrante** no número | Roteamento / URA        |
| `voice.call.ringing`          | Destino tocando                | UI de status            |
| `voice.call.answered`         | Chamada atendida               | Iniciar fluxo, cobrança |
| `voice.call.completed`        | Chamada encerrada              | Fechar ticket, billing  |
| `voice.call.failed`           | Não completou                  | Retentar ou alertar     |
| `voice.call.dtmf`             | Cliente digitou tecla          | Menu interativo         |
| `voice.call.gather.ended`     | Coleta DTMF finalizada         | Próximo passo da URA    |
| `voice.call.recording.ready`  | Gravação disponível            | QA, compliance          |
| `voice.call.machine.detected` | Caixa postal detectada         | Regra de retentativa    |

***

## Payload de cada evento de chamada

<AccordionGroup>
  <Accordion title="voice.call.initiated">
    ```json theme={null}
    {
      "event": "voice.call.initiated",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T14:29:00.000Z",
      "data": {
        "callId": "clxx_call_1",
        "direction": "OUTBOUND",
        "fromE164": "+5511987654321",
        "toE164": "+5511999887766",
        "status": "INITIATED",
        "clientState": "campanha-42"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.received">
    Disparado em chamadas **inbound**. Use com `inboundVoiceAction: WEBHOOK_CONTROL` no número.

    ```json theme={null}
    {
      "event": "voice.call.received",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T15:00:00.000Z",
      "data": {
        "callId": "clxx_call_2",
        "direction": "INBOUND",
        "fromE164": "+5511999887766",
        "toE164": "+5511987654321",
        "status": "RINGING"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.ringing">
    ```json theme={null}
    {
      "event": "voice.call.ringing",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T14:29:15.000Z",
      "data": {
        "callId": "clxx_call_1",
        "direction": "OUTBOUND",
        "fromE164": "+5511987654321",
        "toE164": "+5511999887766",
        "status": "RINGING"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.answered">
    ```json theme={null}
    {
      "event": "voice.call.answered",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T14:30:00.000Z",
      "data": {
        "callId": "clxx_call_1",
        "direction": "OUTBOUND",
        "fromE164": "+5511987654321",
        "toE164": "+5511999887766",
        "status": "ANSWERED",
        "answeredAt": "2026-06-11T14:30:00.000Z"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.completed">
    ```json theme={null}
    {
      "event": "voice.call.completed",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T14:32:00.000Z",
      "data": {
        "callId": "clxx_call_1",
        "direction": "OUTBOUND",
        "fromE164": "+5511987654321",
        "toE164": "+5511999887766",
        "status": "COMPLETED",
        "durationSecs": 120,
        "hangupCause": "normal_clearing"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.failed">
    ```json theme={null}
    {
      "event": "voice.call.failed",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T14:29:45.000Z",
      "data": {
        "callId": "clxx_call_1",
        "direction": "OUTBOUND",
        "fromE164": "+5511987654321",
        "toE164": "+5511999887766",
        "status": "FAILED",
        "hangupCause": "no_answer"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.dtmf">
    ```json theme={null}
    {
      "event": "voice.call.dtmf",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T14:30:20.000Z",
      "data": {
        "callId": "clxx_call_1",
        "dtmfDigits": "1"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.gather.ended">
    ```json theme={null}
    {
      "event": "voice.call.gather.ended",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T14:30:35.000Z",
      "data": {
        "callId": "clxx_call_1",
        "gatherResult": "12345678901"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.recording.ready">
    ```json theme={null}
    {
      "event": "voice.call.recording.ready",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T14:33:00.000Z",
      "data": {
        "callId": "clxx_call_1",
        "recordingId": "clxx_rec_1"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.machine.detected">
    ```json theme={null}
    {
      "event": "voice.call.machine.detected",
      "workspaceId": "clxx123...",
      "instanceId": "",
      "timestamp": "2026-06-11T14:30:05.000Z",
      "data": {
        "callId": "clxx_call_1",
        "machineDetectionResult": "machine"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Inbound com webhook

Quando o número usa `inboundVoiceAction: WEBHOOK_CONTROL`:

1. Receba **`voice.call.received`**
2. Controle a sessão com ações na API (`speak`, `gather`, `transfer`, `hangup`)
3. Acompanhe **`voice.call.answered`**, **`voice.call.dtmf`**, **`voice.call.completed`**, etc.

Configuração do número: [Números de telefone, Quick Start](/phone-numbers-api/como-funciona/quick-start).

***

## Próximos passos

* [Quick Start](/voice-api/como-funciona/quick-start): originar e controlar
* [Introdução](/voice-api/como-funciona/introducao): ciclo da chamada
* [Escopos](/voice-api/como-funciona/escopos-da-api-key): permissões da chave
* [Números de telefone](/phone-numbers-api/como-funciona/introducao): contratar e configurar linha
* [Webhooks (guia geral)](/guides/webhooks/index)