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

> Notificaciones de llamadas de voz en tiempo real (voice.call.*).

<Tip>
  Con la API usted **pregunta**; con webhooks Notifique **avisa**. Excelente para IVR, marcadores y facturación por minuto, sin sondeo de estado.
</Tip>

## En breve

* Cada entrega es un **POST** `application/json` a tu URL registrada.
* Las llamadas usan **`voice.call.*`**; no confundir con `message.*` (WhatsApp) o `sms.*`.
* El ciclo de vida del número contratado (`phone_number.*`) está documentado en [Números de teléfono, Eventos](/es/phone-numbers-api/como-funciona/eventos-do-webhooks).
* `instanceId` está **vacío** (voz no usa instancia de canal).
* Responda **2xx rápidamente**; el procesamiento pesado va a su cola.

Configuración general: [Webhooks](/es/guides/webhooks/index). Seguridad (firma HMAC): [Seguridad del webhook](/es/guides/webhooks/seguranca).

***

## Cómo se ve el POST

| Campo         | Descripción                                   |
| ------------- | --------------------------------------------- |
| `event`       | Nombre del evento (ej. `voice.call.answered`) |
| `workspaceId` | ID del espacio de trabajo                     |
| `instanceId`  | Siempre vacío para voz                        |
| `timestamp`   | ISO 8601, use para anti-replay                |
| `data`        | Campos de llamada o número (**camelCase**)    |

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

***

## Qué debe devolver tu servidor

| Respuesta               | Efecto                                    |
| ----------------------- | ----------------------------------------- |
| **2xx** en \~10 s       | Evento entregado; eliminado de la cola    |
| **4xx / 5xx / timeout** | Reintento automático (5 min, 30 min, 2 h) |

<Note>
  ¿Procesamiento lento? Devuelva **200** inmediatamente y procese en segundo plano.
</Note>

***

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

| Evento                        | Cuándo se dispara              | Qué hacer con ello         |
| ----------------------------- | ------------------------------ | -------------------------- |
| `voice.call.initiated`        | Marcación saliente iniciada    | Log, CRM                   |
| `voice.call.received`         | Llamada **entrante** al número | Enrutamiento / IVR         |
| `voice.call.ringing`          | Destino sonando                | UI de estado               |
| `voice.call.answered`         | Llamada contestada             | Iniciar flujo, facturación |
| `voice.call.completed`        | Llamada finalizada             | Cerrar ticket, facturación |
| `voice.call.failed`           | No se completó                 | Reintentar o alertar       |
| `voice.call.dtmf`             | Cliente presionó tecla         | Menú interactivo           |
| `voice.call.gather.ended`     | Recolección DTMF terminada     | Siguiente paso IVR         |
| `voice.call.recording.ready`  | Grabación disponible           | QA, cumplimiento           |
| `voice.call.machine.detected` | Buzón de voz detectado         | Regla de reintento         |

***

## Carga útil por evento de llamada

<AccordionGroup>
  <Accordion title="voice.call.initiated" />

  <Accordion title="voice.call.received">
    Se activa en llamadas **entrantes**. Úselo con `inboundVoiceAction: WEBHOOK_CONTROL` en el número.
  </Accordion>

  <Accordion title="voice.call.ringing" />

  <Accordion title="voice.call.answered" />

  <Accordion title="voice.call.completed" />

  <Accordion title="voice.call.failed" />

  <Accordion title="voice.call.dtmf" />

  <Accordion title="voice.call.gather.ended" />

  <Accordion title="voice.call.recording.ready" />

  <Accordion title="voice.call.machine.detected" />
</AccordionGroup>

***

## Entrante con webhook

Cuando el número usa `inboundVoiceAction: WEBHOOK_CONTROL`:

1. Reciba **`voice.call.received`**
2. Controle la sesión con acciones API (`speak`, `gather`, `transfer`, `hangup`)
3. Siga **`voice.call.answered`**, **`voice.call.dtmf`**, **`voice.call.completed`**, etc.

Configuración del número: [Números de teléfono, Inicio rápido](/es/phone-numbers-api/como-funciona/quick-start).

***

## Próximos pasos

* [Inicio rápido](/es/voice-api/como-funciona/quick-start): originar y controlar
* [Introducción](/es/voice-api/como-funciona/introducao): ciclo de vida de la llamada
* [Ámbitos](/es/voice-api/como-funciona/escopos-da-api-key): permisos de clave
* [Números de teléfono](/es/phone-numbers-api/como-funciona/introducao): contratar y configurar línea
* [Webhooks (guía general)](/es/guides/webhooks/index)