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 todos los eventos existentes:

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

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.

Deshabilitar temporalmente

{ "status": "DISABLED" }

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

{ "status": "ENABLED" }

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

Ejemplo:

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

description

string

Nueva descripción

events

enum<string>[]

Nueva lista de eventos: sustituye todos los eventos existentes

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

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

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

Habilitar o rotar la firma HMAC

Deshabilitar temporalmente

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

​Conceptos

​Actualizar los eventos

​Habilitar o rotar la firma HMAC

​Deshabilitar temporalmente

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Conceptos

Actualizar los eventos

Habilitar o rotar la firma HMAC

Deshabilitar temporalmente