> ## Documentation Index > Fetch the complete documentation index at: https://developer.omni.z-api.io/llms.txt > Use this file to discover all available pages before exploring further. # Atualizar webhook padrão > Atualize a configuração de um webhook padrão existente ## Conceituação Atualiza parcialmente um webhook padrão. Apenas os campos enviados no body são atualizados; os demais permanecem como estão. ### Atualizar eventos Se enviar o campo `events`, a lista substitui os eventos existentes e deve conter só eventos de canal (evento de template resulta em `422`). Lista vazia resulta em `400`: para manter os eventos, omita o campo. ```json theme={null} { "events": ["MESSAGE_RECEIVED", "CONNECTED", "DISCONNECTED"] } ``` ### Desabilitar temporariamente ```json theme={null} { "status": "DISABLED" } ``` Para reativar, envie `{ "status": "ENABLED" }`. O webhook desabilitado continua contando no limite de 5 do workspace. ### Formato `payloadFormat` aceita `DEFAULT` e `Z_API`. `CHATWOOT` resulta em `422`. ### Assinatura HMAC `signing: true` gera um novo `secret`, retornado apenas nesta resposta; `signing: false` desliga a assinatura. Sem `signing: true`, a resposta traz `secret: null` e o segredo gravado não muda. > [!WARNING] > > `signing: true` gera um `secret` novo **toda vez**, inclusive quando a assinatura já estava ligada e você só queria mudar outro campo. Para manter o segredo atual, **omita** o campo `signing`. Para validar a assinatura, veja [Assinatura HMAC](/webhooks/signature.md). > [!NOTE] > > A URL só é conferida quando muda. Com uma URL nova, valem as mesmas regras da criação: absoluta, `http` ou `https`, até 2048 caracteres, com host que resolve só para endereços públicos. ## OpenAPI ````yaml pt/webhooks/openapi-default.json PATCH /v1/default-instance-webhooks/{webhookId} openapi: 3.1.0 info: title: Omni Z-API - Webhook padrão do workspace description: >- API para criar e gerenciar o webhook padrão do workspace: um webhook sem canal que recebe os eventos de todo canal do workspace que não tem webhook próprio ativo. Aceita os eventos de canal, nos formatos `DEFAULT` e `Z_API`, com até 5 por workspace. Não exige a role ENTERPRISE: basta uma secret key válida de um workspace ativo. version: 1.0.0 servers: - url: https://api.omni.z-api.io security: - bearerAuth: [] paths: /v1/default-instance-webhooks/{webhookId}: parameters: - name: webhookId in: path required: true description: ID do webhook padrão schema: type: string example: 5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B patch: tags: - Webhook padrão summary: Atualizar webhook padrão description: >- Atualiza parcialmente um webhook padrão: campo omitido não muda. `events` substitui a lista inteira. `status: "DISABLED"` pausa o webhook sem excluí-lo. `signing: true` gera um `secret` novo, devolvido só nesta resposta. operationId: updateDefaultInstanceWebhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateDefaultWebhookRequest' examples: disable: summary: Desabilitar value: status: DISABLED replaceEvents: summary: Trocar os eventos value: events: - MESSAGE_RECEIVED - CONNECTED - DISCONNECTED rotateSecret: summary: Gerar um secret novo value: signing: true responses: '200': description: >- Webhook padrão atualizado. O `secret` vem `null`, salvo quando o pedido traz `signing: true`. content: application/json: schema: $ref: '#/components/schemas/DefaultWebhookCreatedResponse' example: id: 5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B channelId: null instanceId: null url: https://app.suaempresa.com/webhooks/omni-zapi description: Eventos de todos os canais events: - MESSAGE_RECEIVED - MESSAGE_STATUS - DISCONNECTED status: DISABLED signing: false secret: null auth: type: NONE configured: false payloadFormat: DEFAULT customAttributes: {} createdAt: '2026-10-22T15:00:00.000+00:00' updatedAt: '2026-10-22T15:30:00.000+00:00' '400': description: >- Corpo inválido, URL nova recusada ou secret key inválida. Nada é gravado. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalidKey: summary: Secret key ausente ou inválida value: error: Authorization invalid ipNotAllowed: summary: IP fora da lista de IPs permitidos do workspace value: error: 203.0.113.10 not allowed emptyEvents: summary: '`events` enviado como lista vazia' value: error: Events cannot be empty when provided unknownEvent: summary: Nome de evento desconhecido, nulo ou em branco value: error: events contains an unknown or empty event name invalidStatus: summary: '`status` fora de `ENABLED` e `DISABLED`' value: error: status must be one of [ENABLED, DISABLED] invalidUrl: summary: URL fora do formato value: error: >- Invalid webhook URL: use an absolute http or https URL up to 2048 characters urlNotAllowed: summary: Host da URL resolve para endereço não público value: error: >- Webhook URL not allowed: the host must resolve only to public addresses missingCredentials: summary: Tipo de autenticação sem a credencial value: error: Credentials are required when auth type is not NONE '404': description: >- Não há webhook padrão com esse id no workspace. Um id de outro workspace, de um webhook de canal ou de um webhook de template recebe a mesma resposta. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Webhook not found '422': description: >- Evento que não é de canal, formato `CHATWOOT` ou workspace inativo. Nada é gravado. content: application/json: schema: $ref: '#/components/schemas/Error' examples: templateEvent: summary: Evento de template (ou outro evento que não é de canal) value: error: >- Default instance webhooks cannot subscribe to template events chatwoot: summary: Formato `CHATWOOT` value: error: >- Default instance webhooks do not support CHATWOOT payload format: configure Chatwoot on the channel inactiveWorkspace: summary: Workspace excluído ou inexistente value: error: Webhook management requires an active workspace '503': description: Não foi possível conferir o destino da URL agora. Tente de novo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Could not verify the webhook URL now, try again components: schemas: UpdateDefaultWebhookRequest: type: object description: >- Todos os campos são opcionais: apenas os campos enviados são atualizados. properties: url: type: string description: Nova URL de destino. Só a URL diferente da gravada é conferida. example: https://nova-url.suaempresa.com/webhooks/omni-zapi description: type: string description: Descrição opcional do webhook example: Eventos de todos os canais events: type: array description: >- Nova lista de eventos de canal. Substitui a lista inteira. Para manter os eventos, omita o campo. items: type: string enum: - MESSAGE_RECEIVED - MESSAGE_DELIVERY - MESSAGE_STATUS - RECEIVED_STATUS - RECEIVED_AND_DELIVERY - CONNECTED - DISCONNECTED - PRESENCE_CHAT - INITIAL_DATA - BLOCK example: - MESSAGE_RECEIVED - MESSAGE_STATUS - DISCONNECTED status: type: string enum: - ENABLED - DISABLED description: >- `DISABLED` pausa o webhook sem excluí-lo; `ENABLED` volta a habilitá-lo signing: type: boolean description: >- `true` gera um `secret` novo (devolvido só nesta resposta), mesmo que a assinatura já estivesse ligada. `false` desliga a assinatura. Omita para não mudar. authType: type: string enum: - NONE - BEARER - API_KEY - BASIC - CUSTOM_HEADER description: Tipo de autenticação (forma plana). Alternativa ao objeto `auth`. token: type: string description: Credencial para `BEARER` (forma plana) key: type: string description: Credencial para `API_KEY` (forma plana) auth: $ref: '#/components/schemas/WebhookAuth' payloadFormat: type: string enum: - DEFAULT - Z_API description: >- `DEFAULT` ou `Z_API`. `CHATWOOT` é recusado com `422`. Omita para não mudar. customAttributes: type: object description: Mapa livre de atributos extras additionalProperties: true DefaultWebhookCreatedResponse: type: object properties: id: type: string description: ID do webhook padrão example: 5B7E3A90C2D14F6A8E1B2C3D4E5F6A7B channelId: type: - string - 'null' description: 'Sempre `null`: o webhook padrão não pertence a um canal' example: null instanceId: type: - string - 'null' description: Sempre `null`. Campo legado, mantido por compatibilidade deprecated: true example: null url: type: string example: https://app.suaempresa.com/webhooks/omni-zapi description: type: - string - 'null' example: Eventos de todos os canais events: type: array items: type: string enum: - MESSAGE_RECEIVED - MESSAGE_DELIVERY - MESSAGE_STATUS - RECEIVED_STATUS - RECEIVED_AND_DELIVERY - CONNECTED - DISCONNECTED - PRESENCE_CHAT - INITIAL_DATA - BLOCK status: type: string enum: - ENABLED - DISABLED description: '`ENABLED` ou `DISABLED`' signing: type: boolean description: '`true` quando a assinatura HMAC está ligada' secret: type: - string - 'null' description: >- Segredo da assinatura HMAC. Vem preenchido só na resposta que o gerou (`signing: true`); nas demais, `null`. auth: $ref: '#/components/schemas/WebhookAuthInfo' payloadFormat: type: string enum: - DEFAULT - Z_API customAttributes: type: object additionalProperties: true createdAt: type: string format: date-time description: Data de criação updatedAt: type: string format: date-time description: Data da última alteração Error: type: object description: Erro properties: error: type: string description: Mensagem do erro WebhookAuth: type: object description: Como o Omni Z-API se autentica ao chamar a sua URL properties: type: type: string enum: - NONE - BEARER - API_KEY - BASIC - CUSTOM_HEADER description: Tipo de autenticação example: BEARER token: type: string description: >- Token para `BEARER`, enviado no header `Authorization: Bearer ` key: type: string description: Chave para `API_KEY` username: type: string description: Usuário para `BASIC` password: type: string description: Senha para `BASIC` headerName: type: string description: Nome do header para `CUSTOM_HEADER` example: X-Api-Key headerValue: type: string description: Valor do header para `CUSTOM_HEADER` WebhookAuthInfo: type: object description: Resumo da autenticação configurada. As credenciais não são retornadas. properties: type: type: string enum: - NONE - BEARER - API_KEY - BASIC - CUSTOM_HEADER example: NONE configured: type: boolean description: '`true` quando há credencial configurada' example: false securitySchemes: bearerAuth: type: http scheme: bearer description: Secret Key gerada no painel de Segurança do Omni Z-API ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.