Actualizar webhook

curl --request PATCH \
  --url https://api.omni.z-api.io/v1/channels/{channelId}/webhooks/{webhookId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "DISABLED"
}
'

{
  "id": "A1B2C3D4E5F6789012345678901234AB",
  "channelId": "019E4C54B1B375A28970B605CA9B03C3",
  "instanceId": "019E4C54B1B375A28970B605CA9B03C3",
  "url": "https://app.suempresa.com/webhooks/omni-zapi",
  "description": "Webhook principal de producción",
  "events": [
    "MESSAGE_RECEIVED",
    "MESSAGE_STATUS"
  ],
  "status": "ENABLED",
  "signing": true,
  "secret": "d4e5f6789012345678901234abcdef0123456789abcdef0123456789ab12c3d4",
  "auth": {
    "type": "BEARER",
    "configured": true
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2025-01-15T10:30:00.000+0000",
  "updatedAt": "2025-01-20T14:00:00.000+0000"
}

PATCH

channels

{channelId}

webhooks

{webhookId}

curl --request PATCH \
  --url https://api.omni.z-api.io/v1/channels/{channelId}/webhooks/{webhookId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "DISABLED"
}
'

{
  "id": "A1B2C3D4E5F6789012345678901234AB",
  "channelId": "019E4C54B1B375A28970B605CA9B03C3",
  "instanceId": "019E4C54B1B375A28970B605CA9B03C3",
  "url": "https://app.suempresa.com/webhooks/omni-zapi",
  "description": "Webhook principal de producción",
  "events": [
    "MESSAGE_RECEIVED",
    "MESSAGE_STATUS"
  ],
  "status": "ENABLED",
  "signing": true,
  "secret": "d4e5f6789012345678901234abcdef0123456789abcdef0123456789ab12c3d4",
  "auth": {
    "type": "BEARER",
    "configured": true
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2025-01-15T10:30:00.000+0000",
  "updatedAt": "2025-01-20T14:00:00.000+0000"
}

Conceptos

Actualiza parcialmente la configuración de un webhook. Solo se actualizan los campos que envías en el body; el resto se mantiene sin cambios.

Actualizar los eventos

Al enviar el campo events, la lista sustituye los eventos del webhook:

{ "events": ["MESSAGE_RECEIVED", "MESSAGE_STATUS", "CONNECTED"] }

La lista no puede estar vacía: "events": [] devuelve 400 con {"error": "Events cannot be empty when provided"}. Para mantener los eventos, omite el campo.
Un elemento nulo, en blanco o con un nombre que no existe devuelve 400 con {"error": "events contains an unknown or empty event name"}, y no se modifica nada.

Evento que la API todavía no conoce. Un webhook puede tener guardado un evento que esta versión de la API todavía no conoce, por ejemplo un evento nuevo suscrito desde el panel antes de llegar a la API. Ese evento no aparece en events en las respuestas y se mantiene cuando sustituyes los eventos: el PATCH sustituye solo los eventos que la API conoce. Un webhook que solo tiene eventos así aparece con events: [].

Cambiar la URL

La nueva url sigue las mismas reglas que en la creación (consulta URL del webhook). Solo se comprueba cuando cambia: un PATCH sin url, o con la URL ya guardada, no se rechaza por ella.

Habilitar o rotar la firma HMAC

Si envías signing: true, se genera un secret nuevo y se devuelve en esa respuesta. Úsalo también para rotar el secret sin necesidad de recrear el webhook.

{ "signing": true }

El nuevo secret se devuelve solo en esa respuesta. Guárdalo antes de salir de la página o de cerrar la sesión.

signing: true rota el secret cada vez, incluso cuando la firma ya estaba habilitada y solo querías cambiar otro campo en la misma petición. Para no rotar, omite el campo signing.

Para validar la firma con el secret nuevo, consulta Firma HMAC.

Deshabilitar temporalmente

{ "status": "DISABLED" }

Mientras esté DISABLED, el webhook deja de recibir eventos. Para reactivarlo:

{ "status": "ENABLED" }

Un status distinto de ENABLED y DISABLED devuelve 400 con {"error": "status must be one of [ENABLED, DISABLED]"}.

El webhookId se obtiene en la respuesta del endpoint Crear webhook o Listar webhooks.

Autorizaciones

Authorization

string

header

requerido

Secret Key generada en el panel de Seguridad de Omni Z-API

Parámetros de ruta

channelId

string

requerido

ID del canal

Ejemplo:

"019E4C54B1B375A28970B605CA9B03C3"

webhookId

string

requerido

ID del webhook

Ejemplo:

"A1B2C3D4E5F6789012345678901234AB"

Cuerpo

application/json

Todos los campos son opcionales: solo se actualizan los campos que se envían.

url

string

Nueva URL de destino, con las mismas reglas que en la creación. Solo se comprueba cuando cambia.

Ejemplo:

"https://nova-url.suempresa.com/webhooks/omni-zapi"

description

string

Nueva descripción

events

enum<string>[]

Nueva lista de eventos. Sustituye los eventos que la API conoce; un evento guardado que la API todavía no conoce se mantiene. No puede estar vacía (400).

Opciones disponibles:

MESSAGE_RECEIVED,

MESSAGE_DELIVERY,

MESSAGE_STATUS,

RECEIVED_STATUS,

RECEIVED_AND_DELIVERY,

CONNECTED,

DISCONNECTED,

PRESENCE_CHAT,

INITIAL_DATA,

BLOCK

status

enum<string>

DISABLED pausa la entrega de eventos sin eliminar el webhook Cualquier otro valor devuelve 400.

Opciones disponibles:

ENABLED,

DISABLED

signing

boolean

Habilita o rota la firma HMAC. Genera un secret nuevo que se devuelve en la respuesta.

auth

object

Configura cómo se autentica Omni Z-API al llamar a tu URL

Show child attributes

payloadFormat

enum<string>

Opciones disponibles:

DEFAULT,

Z_API,

CHATWOOT

customAttributes

object

Respuesta

Webhook actualizado correctamente. El campo secret se devuelve solo cuando se ha habilitado signing en esta actualización.

string

ID único del webhook

Ejemplo:

"A1B2C3D4E5F6789012345678901234AB"

channelId

string

ID del canal al que pertenece el webhook

Ejemplo:

"019E4C54B1B375A28970B605CA9B03C3"

instanceId

string

obsoleto

Obsoleto: usa channelId

Ejemplo:

"019E4C54B1B375A28970B605CA9B03C3"

url

string

URL de destino de los eventos

Ejemplo:

"https://app.suempresa.com/webhooks/omni-zapi"

description

string | null

Descripción del webhook

Ejemplo:

"Webhook principal de producción"

events

string[]

Tipos de evento configurados Un evento guardado que la API todavía no conoce no aparece aquí.

Ejemplo:

["MESSAGE_RECEIVED", "MESSAGE_STATUS"]

status

enum<string>

Estado actual del webhook

Opciones disponibles:

ENABLED,

DISABLED

Ejemplo:

"ENABLED"

signing

boolean

Indica si la firma HMAC está habilitada

Ejemplo:

true

auth

object

Resumen de la autenticación configurada: las credenciales no se devuelven por seguridad

Show child attributes

payloadFormat

enum<string>

Formato del payload entregado

Opciones disponibles:

DEFAULT,

Z_API,

CHATWOOT

Ejemplo:

"DEFAULT"

customAttributes

object

Atributos extra configurados

Ejemplo:

{}

createdAt

string<date-time>

Fecha de creación

Ejemplo:

"2025-01-15T10:30:00.000+0000"

updatedAt

string<date-time>

Fecha de la última actualización

Ejemplo:

"2025-01-15T10:30:00.000+0000"

secret

string

Secret HMAC de 64 caracteres hexadecimales: se devuelve solo cuando se habilita signing en el create o el update. Guárdalo de forma segura; después no se podrá recuperar.

Ejemplo:

"a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab"

Canales

Mensajes

Plantillas (WhatsApp)

Flows (WhatsApp)

Webhooks

Conceptos

Actualizar los eventos

Cambiar la URL

Habilitar o rotar la firma HMAC

Deshabilitar temporalmente

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

​Conceptos

​Actualizar los eventos

​Cambiar la URL

​Habilitar o rotar la firma HMAC

​Deshabilitar temporalmente

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Conceptos

Actualizar los eventos

Cambiar la URL

Habilitar o rotar la firma HMAC

Deshabilitar temporalmente