> ## Documentation Index
> Fetch the complete documentation index at: https://developer.omni.z-api.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook predeterminado del workspace

> Recibe en un solo lugar los eventos de todos los canales del workspace que no tienen webhook propio

## ¿Qué es el webhook predeterminado?

El webhook predeterminado no pertenece a un canal. Aplica a **todos los canales del workspace** que no tienen un webhook propio activo, incluidos los canales creados después de él.

Úsalo cuando todos tus canales envían los eventos al mismo sistema: registras la URL una vez, en lugar de crear un webhook en cada canal. Cuando un canal necesita un destino distinto, crea un [webhook de canal](/es/webhooks/channel-webhooks.md) en él, y el predeterminado deja de aplicar a ese canal.

> [!NOTE]
>
> La autenticación en tu URL, la firma HMAC y los formatos de payload funcionan como en los demás tipos de webhook. Consulta la [Introducción](/es/webhooks/introduction.md).

## Quién recibe cada evento

Para cada evento de un canal, Omni Z-API decide una sola vez:

1. **El canal tiene al menos un webhook propio activo:** solo reciben los webhooks del canal suscritos a ese evento. El webhook predeterminado no recibe nada de ese canal.
2. **El canal no tiene un webhook propio activo:** reciben los webhooks predeterminados activos suscritos a ese evento.

El mismo evento nunca va al webhook del canal y al predeterminado a la vez.

Un **webhook propio activo** es un webhook del canal con `status` `ENABLED` y al menos un evento suscrito, en cualquier formato, incluido `CHATWOOT`. Un webhook del canal con `status` `DISABLED` no cuenta: si es el único del canal, el predeterminado vuelve a aplicar a ese canal.

> [!WARNING]
>
> **El predeterminado no completa los eventos que le faltan al webhook del canal.** Si el canal tiene un webhook activo solo con `MESSAGE_STATUS`, un mensaje recibido en ese canal no va a nadie, ni siquiera al predeterminado. Para recibir `MESSAGE_RECEIVED` de ese canal, suscribe el evento en el webhook del canal, o deshabilita el webhook del canal para que el predeterminado vuelva a aplicar.

Un canal eliminado no recibe eventos por el predeterminado.

## Eventos admitidos

El webhook predeterminado admite los mismos eventos que el [webhook de canal](/es/webhooks/channel-webhooks.md):

| Evento | Cuándo se dispara |
| - | - |
| `MESSAGE_RECEIVED` | Se recibió un mensaje en el canal |
| `MESSAGE_DELIVERY` | Confirmación de entrega de un mensaje enviado |
| `MESSAGE_STATUS` | Actualización de estado de un mensaje (leído, fallido, etc.) |
| `RECEIVED_STATUS` | Combinación de recepción y estado |
| `RECEIVED_AND_DELIVERY` | Combinación de recepción y entrega |
| `CONNECTED` | El canal se conectó |
| `DISCONNECTED` | El canal se desconectó |
| `PRESENCE_CHAT` | Indicador de presencia o de escritura de un contacto |
| `INITIAL_DATA` | Sincronización inicial de datos al conectar el canal |
| `BLOCK` | Evento de bloqueo de contacto |

Como el predeterminado aplica a canales de tipos distintos, los eventos no se comprueban contra el tipo de cada canal: un evento que el canal no emite simplemente no llega.

Los eventos de plantilla no se admiten (`422`). Para recibirlos, usa los [webhooks de plantilla](/es/webhooks/template-webhooks.md).

## Formatos

El webhook predeterminado admite `payloadFormat` `DEFAULT` (si se omite) y `Z_API`. El cuerpo que recibes es el mismo de un webhook de canal en el mismo formato. Consulta [Estructura de los payloads](/es/webhooks/payloads.md).

El formato `CHATWOOT` se rechaza, porque cada canal tiene su propia bandeja de entrada en Chatwoot:

```json theme={null}
{ "error": "Default instance webhooks do not support CHATWOOT payload format: configure Chatwoot on the channel" }
```

Configura Chatwoot en el webhook de cada canal. Ese webhook cuenta como webhook propio activo, y el predeterminado deja de aplicar a ese canal.

## Límite por workspace

Cada workspace tiene hasta **5 webhooks predeterminados**, contando los habilitados y los deshabilitados. Por encima de eso, la creación responde `422`:

```json theme={null}
{ "error": "Default instance webhook limit reached (5)" }
```

Eliminar un webhook predeterminado libera el cupo.

## Quién puede gestionarlo

Cualquier secret key válida de un workspace activo puede gestionar el webhook predeterminado. No se requiere el rol **ENTERPRISE**. La secret key sigue sujeta a la lista de IP permitidas del workspace.

Un workspace eliminado recibe `422` en todas las rutas:

```json theme={null}
{ "error": "Webhook management requires an active workspace" }
```

Cada workspace solo ve sus propios webhooks predeterminados. El id de un webhook de otro workspace, de un webhook de canal o de un webhook de plantilla recibe la misma respuesta que un id que no existe: `404` con `{"error": "Webhook not found"}`.

## Cuándo se aplica el cambio

Crear, modificar o eliminar un webhook predeterminado suele aplicarse ya en el siguiente evento. Si hay retraso, el cambio se aplica en un máximo de 5 minutos.

## Gestión

> **[Crear webhook predeterminado](/es/webhooks/create-default-webhook.md)**
>
> Registra una URL para los eventos de todos los canales.

> **[Listar webhooks predeterminados](/es/webhooks/list-default-webhooks.md)**
>
> Consulta los webhooks predeterminados del workspace.

> **[Consultar webhook predeterminado](/es/webhooks/get-default-webhook.md)**
>
> Consulta un webhook predeterminado concreto.

> **[Actualizar webhook predeterminado](/es/webhooks/update-default-webhook.md)**
>
> Actualiza URL, eventos, autenticación, formato o estado.

> **[Eliminar webhook predeterminado](/es/webhooks/delete-default-webhook.md)**
>
> Elimina un webhook predeterminado y libera el cupo.

> **[Estructura de los payloads](/es/webhooks/payloads.md)**
>
> Ejemplos de los payloads recibidos para cada tipo de mensaje.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.