Saltar al contenido principal
PATCH

​
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):
  • 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.

​
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.
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, consulta Firma HMAC.

​
Deshabilitar temporalmente

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

​
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, con las mismas reglas que en la creación. Solo se comprueba cuando cambia.

Ejemplo:

"https://nueva-url.suempresa.com/webhooks/templates"

​
description
string

Nueva descripción

​
events
enum<string>[]

Si se envía, sustituye los eventos que la API conoce: solo eventos de plantilla (en caso contrario → 422). Un evento guardado que la API todavía no conoce se mantiene. No puede estar vacía (400).

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 Cualquier otro valor devuelve 400.

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.

​
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.

​
id
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://app.suempresa.com/webhooks/templates"

​
description
string | null

Descripción del webhook

Ejemplo:

"Webhook de plantilla"

​
events
enum<string>[]

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

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
Ejemplo:
​
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

​
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