Actualizar webhook de plantilla

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

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://novo-destino/webhook",
  "description": "Webhook de plantilla",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "status": "DISABLED",
  "signing": false,
  "auth": {
    "type": "NONE",
    "configured": false
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2026-07-15T19:00:00.000+00:00",
  "updatedAt": "2026-07-15T19:30:00.000+00:00"
}

{
  "error": "Validation error"
}

{
  "error": "Webhook not found"
}

{
  "error": "Global webhooks (without instance) accept only template events"
}

PATCH

webhooks

{webhookId}

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

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://novo-destino/webhook",
  "description": "Webhook de plantilla",
  "events": [
    "UPDATE_TEMPLATE_STATUS",
    "UPDATE_TEMPLATE_CATEGORY"
  ],
  "status": "DISABLED",
  "signing": false,
  "auth": {
    "type": "NONE",
    "configured": false
  },
  "payloadFormat": "DEFAULT",
  "customAttributes": {},
  "createdAt": "2026-07-15T19:00:00.000+00:00",
  "updatedAt": "2026-07-15T19:30:00.000+00:00"
}

{
  "error": "Validation error"
}

{
  "error": "Webhook not found"
}

{
  "error": "Global webhooks (without instance) accept only template events"
}

Conceptos

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

Actualizar los eventos

Si envías el campo events, la lista sustituye los eventos existentes y debe contener solo eventos de plantilla (en caso contrario → 422):

{ "events": ["UPDATE_TEMPLATE_STATUS", "UPDATE_TEMPLATE_CATEGORY"] }

Firma HMAC

signing: true genera un secret nuevo (que se devuelve solo en esa respuesta); signing: false elimina la firma.

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

Deshabilitar temporalmente

{ "status": "DISABLED" }

Para reactivarlo, envía { "status": "ENABLED" }.

`payloadFormat` se sigue ignorando

En los webhooks de plantilla el formato es siempre DEFAULT, aunque lo envíes en la actualización.

Tras el cambio, el enrutamiento puede tardar hasta unos 5 min en reflejarlo (TTL de la caché).

Autorizaciones

Authorization

string

header

requerido

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

Parámetros de ruta

webhookId

string

requerido

ID del webhook de plantilla

Ejemplo:

"8F2C00000000000000000000000000A1"

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://novo-destino/webhook"

description

string

Nueva descripción

events

enum<string>[]

Si se envía, sustituye la lista de eventos: solo eventos de plantilla (en caso contrario → 422).

Eventos de plantilla admitidos: UPDATE_TEMPLATE_STATUS (actualización del estado de la plantilla: aprobada, rechazada, etc.) y UPDATE_TEMPLATE_CATEGORY (actualización de la categoría de la plantilla).

Opciones disponibles:

UPDATE_TEMPLATE_STATUS,

UPDATE_TEMPLATE_CATEGORY

status

enum<string>

DISABLED pausa la entrega de eventos sin eliminar el webhook

Opciones disponibles:

ENABLED,

DISABLED

signing

boolean

true genera un secret nuevo; false elimina la firma

authType

enum<string>

NONE borra la autenticación; el resto la reconfiguran

Opciones disponibles:

NONE,

BEARER,

API_KEY,

BASIC,

CUSTOM_HEADER

token

string

Credencial para BEARER

key

string

Credencial para API_KEY

auth

object

Forma anidada de la autenticación. Para BASIC usa username+password; para CUSTOM_HEADER usa headerName+headerValue.

Show child attributes

payloadFormat

enum<string>

Ignorado en los webhooks de plantilla

Opciones disponibles:

DEFAULT

customAttributes

object

Respuesta

Webhook de plantilla actualizado. El campo secret se devuelve solo cuando signing = true en esta actualización.

string

ID único del webhook de plantilla

Ejemplo:

"8F2C00000000000000000000000000A1"

channelId

string | null

Siempre null en los webhooks de plantilla

Ejemplo:

null

instanceId

string | null

obsoleto

Obsoleto y siempre null en los webhooks de plantilla

Ejemplo:

null

url

string

URL de destino de los eventos

Ejemplo:

"https://destino/webhook"

description

string | null

Descripción del webhook

Ejemplo:

"Webhook de plantilla"

events

enum<string>[]

Eventos de plantilla configurados

Opciones disponibles:

UPDATE_TEMPLATE_STATUS,

UPDATE_TEMPLATE_CATEGORY

Ejemplo:

[
  "UPDATE_TEMPLATE_STATUS",
  "UPDATE_TEMPLATE_CATEGORY"
]

status

enum<string>

Estado actual del webhook

Opciones disponibles:

ENABLED,

DISABLED

Ejemplo:

"ENABLED"

signing

boolean

Indica si la firma HMAC está habilitada

Ejemplo:

false

auth

object

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

Show child attributes

payloadFormat

enum<string>

Siempre DEFAULT en los webhooks de plantilla

Opciones disponibles:

DEFAULT

Ejemplo:

"DEFAULT"

customAttributes

object

Ejemplo:

{}

createdAt

string<date-time>

Ejemplo:

"2026-07-15T19:00:00.000+00:00"

updatedAt

string<date-time>

Ejemplo:

"2026-07-15T19:00:00.000+00:00"

secret

string | null

Secret HMAC de 64 caracteres hexadecimales: se devuelve solo cuando signing = true en el create o el update. Es null cuando la firma está deshabilitada. Después no se podrá recuperar.

Ejemplo:

null

Canales

Mensajes

Plantillas (WhatsApp)

Flows (WhatsApp)

Webhooks

Actualizar webhook de plantilla

Conceptos

Actualizar los eventos

Firma HMAC

Deshabilitar temporalmente

`payloadFormat` se sigue ignorando

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

​Conceptos

​Actualizar los eventos

​Firma HMAC

​Deshabilitar temporalmente

​payloadFormat se sigue ignorando

Autorizaciones

Parámetros de ruta

Cuerpo

Respuesta

Conceptos

Actualizar los eventos

Firma HMAC

Deshabilitar temporalmente

`payloadFormat` se sigue ignorando