Atualizar webhook

Atualize a configuração de um webhook existente

PATCH /v1/channels/{channelId}/webhooks/{webhookId}

cURL

disable

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

200

afterEnableSigning

{
  "id": "A1B2C3D4E5F6789012345678901234AB",
  "channelId": "019E4C54B1B375A28970B605CA9B03C3",
  "instanceId": "019E4C54B1B375A28970B605CA9B03C3",
  "url": "https://app.suaempresa.com/webhooks/omni-zapi",
  "description": "Webhook principal de produção",
  "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"
}

​

Conceituação

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

​

Atualizar eventos

Ao enviar o campo events, a lista substitui todos os eventos existentes:

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

​

Habilitar ou rotacionar a assinatura HMAC

Se você enviar signing: true, um novo secret é gerado e retornado nesta resposta. Use isso também para rotacionar o secret sem precisar recriar o webhook.

{ "signing": true }

O novo secret é retornado apenas nesta resposta. Armazene-o antes de sair da página ou fechar a sessão.

​

Desabilitar temporariamente

{ "status": "DISABLED" }

O webhook para de receber eventos enquanto estiver DISABLED. Para reativar:

{ "status": "ENABLED" }

O webhookId é obtido no retorno do endpoint Criar webhook ou Listar webhooks.

Autorizações

Authorization · string · header · obrigatório

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

Parâmetros de caminho

channelId · string · obrigatório

ID do canal

Exemplo:

"019E4C54B1B375A28970B605CA9B03C3"

webhookId · string · obrigatório

ID do webhook

Exemplo:

"A1B2C3D4E5F6789012345678901234AB"

Corpo

application/json

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

url · string

Nova URL de destino

Exemplo:

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

description · string

Nova descrição

events · enum<string>[]

Nova lista de eventos — substitui todos os eventos existentes

Opções disponíveis: MESSAGE_RECEIVED, MESSAGE_DELIVERY, MESSAGE_STATUS, RECEIVED_STATUS, RECEIVED_AND_DELIVERY, CONNECTED, DISCONNECTED, PRESENCE_CHAT, INITIAL_DATA, BLOCK

status · enum<string>

DISABLED pausa a entrega de eventos sem excluir o webhook

Opções disponíveis: ENABLED, DISABLED

signing · boolean

Habilita ou rotaciona a assinatura HMAC. Gera um novo secret retornado na resposta.

auth · object

Configura como o Omni Z-API se autentica ao chamar sua URL

Show child attributes

payloadFormat · enum<string>

Opções disponíveis: DEFAULT, Z_API, CHATWOOT

customAttributes · object

Resposta

200

application/json

Webhook atualizado com sucesso. O campo secret é retornado apenas quando signing foi habilitado nesta atualização.

id · string

ID único do webhook

Exemplo:

"A1B2C3D4E5F6789012345678901234AB"

channelId · string

ID do canal ao qual o webhook pertence

Exemplo:

"019E4C54B1B375A28970B605CA9B03C3"

instanceId · string · obsoleto

Descontinuado — use channelId

Exemplo:

"019E4C54B1B375A28970B605CA9B03C3"

url · string

URL de destino dos eventos

Exemplo:

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

description · string | null

Descrição do webhook

Exemplo:

"Webhook principal de produção"

events · string[]

Tipos de evento configurados

Exemplo:

["MESSAGE_RECEIVED", "MESSAGE_STATUS"]

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:

true

auth · object

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

Show child attributes

payloadFormat · enum<string>

Formato do payload entregue

Opções disponíveis: DEFAULT, Z_API, CHATWOOT

Exemplo:

"DEFAULT"

customAttributes · object

Atributos extras configurados

Exemplo:

{}

createdAt · string<date-time>

Data de criação

Exemplo:

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

updatedAt · string<date-time>

Data da última atualização

Exemplo:

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

secret · string

Segredo HMAC de 64 caracteres hex — retornado apenas quando signing é habilitado no create ou update. Armazene-o com segurança; não poderá ser recuperado depois.

Exemplo:

"a3f1c2d4e5b6789012345678901234abcdef0123456789abcdef0123456789ab"