Atualizar webhook de template

Atualize a configuração de um webhook de template existente

PATCH /v1/webhooks/{webhookId}

cURL

updateUrlAndStatus

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"
}
'

200

{
  "id": "8F2C00000000000000000000000000A1",
  "channelId": null,
  "instanceId": null,
  "url": "https://novo-destino/webhook",
  "description": "Webhook de template",
  "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"
}

​

Conceituação

Atualiza parcialmente a configuração de um webhook de template. Apenas os campos enviados no body são atualizados — os demais permanecem inalterados.

​

Atualizar eventos

Se enviar o campo events, a lista substitui os eventos existentes e deve conter somente eventos de template (senão → 422):

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

​

Assinatura HMAC

signing: true gera um novo secret (retornado apenas nesta resposta); signing: false remove a assinatura.

O novo secret é retornado apenas nesta resposta. Armazene-o antes de fechar a sessão.

​

Desabilitar temporariamente

{ "status": "DISABLED" }

Para reativar, envie { "status": "ENABLED" }.

​

payloadFormat continua ignorado

Para webhooks de template o formato é sempre DEFAULT, mesmo que enviado na atualização.

Após a alteração, o roteamento pode levar até ~5 min para refletir (TTL de cache).

Autorizações

Authorization · string · header · obrigatório

Secret Key gerada no painel de Segurança do Omni Z-API

Parâmetros de caminho

webhookId · string · obrigatório

ID do webhook de template

Exemplo:

"8F2C00000000000000000000000000A1"

Corpo

application/json

Todos os campos são opcionais — apenas os campos enviados são atualizados.

url · string

Nova URL de destino

Exemplo:

"https://novo-destino/webhook"

description · string

Nova descrição

events · enum<string>[]

Se enviado, substitui a lista de eventos — somente eventos de template (senão → 422).

Eventos de template aceitos: UPDATE_TEMPLATE_STATUS (atualização de status do template — aprovado/rejeitado etc.) e UPDATE_TEMPLATE_CATEGORY (atualização de categoria do template).

Opções disponíveis: UPDATE_TEMPLATE_STATUS, UPDATE_TEMPLATE_CATEGORY

status · enum<string>

DISABLED pausa a entrega de eventos sem excluir o webhook

Opções disponíveis: ENABLED, DISABLED

signing · boolean

true gera um novo secret; false remove a assinatura

authType · enum<string>

NONE limpa a autenticação; os demais reconfiguram

Opções disponíveis: NONE, BEARER, API_KEY, BASIC, CUSTOM_HEADER

token · string

Credencial para BEARER

key · string

Credencial para API_KEY

auth · object

Forma aninhada da autenticação. Para BASIC use username+password; para CUSTOM_HEADER use headerName+headerValue.

Show child attributes

payloadFormat · enum<string>

Ignorado para webhooks de template

Opções disponíveis: DEFAULT

customAttributes · object

Resposta

200

application/json

Webhook de template atualizado. O campo secret é retornado apenas quando signing = true nesta atualização.

id · string

ID único do webhook de template

Exemplo:

"8F2C00000000000000000000000000A1"

channelId · string | null

Sempre null para webhooks de template

Exemplo:

null

instanceId · string | null · obsoleto

Descontinuado e sempre null para webhooks de template

Exemplo:

null

url · string

URL de destino dos eventos

Exemplo:

"https://destino/webhook"

description · string | null

Descrição do webhook

Exemplo:

"Webhook de template"

events · enum<string>[]

Eventos de template configurados

Eventos de template aceitos: UPDATE_TEMPLATE_STATUS (atualização de status do template — aprovado/rejeitado etc.) e UPDATE_TEMPLATE_CATEGORY (atualização de categoria do template).

Opções disponíveis: UPDATE_TEMPLATE_STATUS, UPDATE_TEMPLATE_CATEGORY

Exemplo:

[
  "UPDATE_TEMPLATE_STATUS",
  "UPDATE_TEMPLATE_CATEGORY"
]

status · enum<string>

Status atual do webhook

Opções disponíveis: ENABLED, DISABLED

Exemplo:

"ENABLED"

signing · boolean

Indica se a assinatura HMAC está habilitada

Exemplo:

false

auth · object

Resumo da autenticação configurada — credenciais não são retornadas por segurança

Show child attributes

payloadFormat · enum<string>

Sempre DEFAULT para webhooks de template

Opções disponíveis: DEFAULT

Exemplo:

"DEFAULT"

customAttributes · object

Exemplo:

{}

createdAt · string<date-time>

Exemplo:

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

updatedAt · string<date-time>

Exemplo:

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

secret · string | null

Segredo HMAC de 64 caracteres hex — retornado apenas quando signing = true no create/update. null quando a assinatura está desabilitada. Não poderá ser recuperado depois.

Exemplo:

null