Atualizar 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.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"
}

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.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 os eventos do webhook:

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

A lista não pode ser vazia: "events": [] retorna 400 com {"error": "Events cannot be empty when provided"}. Para manter os eventos, omita o campo.
Um item nulo, em branco ou com nome que não existe retorna 400 com {"error": "events contains an unknown or empty event name"}, e nada é alterado.

Evento que a API ainda não conhece. Um webhook pode ter um evento gravado que esta versão da API ainda não conhece, por exemplo um evento novo assinado pelo painel antes de chegar à API. Esse evento não aparece em events nas respostas e é mantido quando você troca os eventos: o PATCH substitui só os eventos que a API conhece. Um webhook que só tem eventos assim aparece com events: [].

Alterar a URL

A nova url segue as mesmas regras da criação (veja URL do webhook). Ela só é conferida quando muda: um PATCH sem url, ou com a URL já gravada, não é recusado por ela.

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.

signing: true rotaciona o secret toda vez, inclusive quando a assinatura já estava habilitada e você só queria mudar outro campo no mesmo request. Para não rotacionar, omita o campo signing.

Para validar a assinatura com o secret novo, veja Assinatura HMAC.

Desabilitar temporariamente

{ "status": "DISABLED" }

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

{ "status": "ENABLED" }

Um status diferente de ENABLED e DISABLED retorna 400 com {"error": "status must be one of [ENABLED, DISABLED]"}.

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, com as mesmas regras da criação. Só é conferida quando muda.

Exemplo:

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

description

string

Nova descrição

events

enum<string>[]

Nova lista de eventos. Substitui os eventos que a API conhece; um evento gravado que a API ainda não conhece é mantido. Não pode ser vazia (400).

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 Outro valor retorna 400.

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

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

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 Evento gravado que a API ainda não conhece não aparece aqui.

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"

Canais

Mensagens

Templates (WhatsApp)

Flows (WhatsApp)

Webhooks

Conceituação

Atualizar eventos

Alterar a URL

Habilitar ou rotacionar a assinatura HMAC

Desabilitar temporariamente

Autorizações

Parâmetros de caminho

Corpo

Resposta

​Conceituação

​Atualizar eventos

​Alterar a URL

​Habilitar ou rotacionar a assinatura HMAC

​Desabilitar temporariamente

Autorizações

Parâmetros de caminho

Corpo

Resposta

Conceituação

Atualizar eventos

Alterar a URL

Habilitar ou rotacionar a assinatura HMAC

Desabilitar temporariamente