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

# Webhook events

> Real-time voice call notifications (voice.call.*).

<Tip>
  With the API you **ask**; with webhooks Notifique **tells you**. Great for IVR, dialers, and per-minute billing, without status polling.
</Tip>

## In brief

* Every delivery is a **POST** `application/json` to your registered URL.
* Calls use **`voice.call.*`**, do not confuse with `message.*` (WhatsApp) or `sms.*`.
* Contracted number lifecycle (`phone_number.*`) is documented under [Phone numbers, Events](/en/phone-numbers-api/como-funciona/eventos-do-webhooks).
* `instanceId` is **empty** (voice does not use a channel instance).
* Respond **2xx quickly**; heavy processing goes to your queue.

General setup: [Webhooks](/en/guides/webhooks/index). Security (HMAC signature): [Webhook security](/en/guides/webhooks/seguranca).

***

## How the POST looks

```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": "campaign-42"
  }
}
```

| Field         | Description                             |
| ------------- | --------------------------------------- |
| `event`       | Event name (e.g. `voice.call.answered`) |
| `workspaceId` | Workspace ID                            |
| `instanceId`  | Always empty for voice                  |
| `timestamp`   | ISO 8601, use for anti-replay           |
| `data`        | Call or number fields (**camelCase**)   |

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

***

## What your server should return

| Response                | Effect                               |
| ----------------------- | ------------------------------------ |
| **2xx** within \~10s    | Event delivered; removed from queue  |
| **4xx / 5xx / timeout** | Automatic retry (5 min, 30 min, 2 h) |

<Note>
  Slow processing? Return **200** immediately and process in the background.
</Note>

***

## Call events (`voice.call.*`)

| Event                         | When it fires              | What to do with it    |
| ----------------------------- | -------------------------- | --------------------- |
| `voice.call.initiated`        | Outbound dial started      | Log, CRM              |
| `voice.call.received`         | **Inbound** call to number | Routing / IVR         |
| `voice.call.ringing`          | Destination ringing        | Status UI             |
| `voice.call.answered`         | Call answered              | Start flow, billing   |
| `voice.call.completed`        | Call ended                 | Close ticket, billing |
| `voice.call.failed`           | Did not complete           | Retry or alert        |
| `voice.call.dtmf`             | Customer pressed key       | Interactive menu      |
| `voice.call.gather.ended`     | DTMF collection finished   | Next IVR step         |
| `voice.call.recording.ready`  | Recording available        | QA, compliance        |
| `voice.call.machine.detected` | Voicemail detected         | Retry rule            |

***

## Payload per call event

<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": "campaign-42"
      }
    }
    ```
  </Accordion>

  <Accordion title="voice.call.received">
    Fires on **inbound** calls. Use with `inboundVoiceAction: WEBHOOK_CONTROL` on the number.

    ```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 with webhook

When the number uses `inboundVoiceAction: WEBHOOK_CONTROL`:

1. Receive **`voice.call.received`**
2. Control the session with API actions (`speak`, `gather`, `transfer`, `hangup`)
3. Track **`voice.call.answered`**, **`voice.call.dtmf`**, **`voice.call.completed`**, etc.

Number setup: [Phone numbers, Quick Start](/en/phone-numbers-api/como-funciona/quick-start).

***

## Next steps

* [Quick Start](/en/voice-api/como-funciona/quick-start): originate and control
* [Introduction](/en/voice-api/como-funciona/introducao): call lifecycle
* [Scopes](/en/voice-api/como-funciona/escopos-da-api-key): key permissions
* [Phone numbers](/en/phone-numbers-api/como-funciona/introducao): contract and configure line
* [Webhooks (general guide)](/en/guides/webhooks/index)