/v1/instances/{id}/webhookConfigurar, desativar ou herdar webhook por ID
Um destino efetivo por instância. Cadastro cria exceção ao global. URL nova começa após o backlog; mesma URL preserva cursor e segredo omitido. action=delete desativa inclusive em mudanças globais; action=inherit volta ao global. groups e call são entregues; qrcode continua ignorado. call é emitido pelas instâncias calls.
Autenticação
Header obrigatório: admintoken. Use o token administrativo do servidor.
Base URL: a API do servidor selecionado, como https://1.atendro.cloud. O domínio wpp.atendro.cloud hospeda a documentação e o console.
Parâmetros de caminho
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
id | string | obrigatório | Identificador devolvido pela API. Comprimento mínimo: 1. Formato: uuid |
Headers adicionais
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
X-Request-Id | string | opcional | ASCII visível sem espaços, 1–128 caracteres. Inválido/ausente é substituído por UUID. Ecoado na resposta. Comprimento máximo: 128 |
Corpo da requisição
Formato: application/json. Corpo obrigatório.
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
action | string | condicional | Valores: "add", "update", "delete", "inherit". Padrão: "add" |
enabled | boolean | opcional | Padrão: true |
url | string | condicional | HTTPS público, sem credenciais/redirects; exceções de laboratório na allowlist. Comprimento máximo: 2048 |
events | string / array<string> | condicional | Entregues: connection, messages, messages_update, messages_edit, groups, limits, undecryptable, call. qrcode, history e chats são aceitos e ignorados, assim como os demais nomes de compatibilidade documentados. |
excludeMessages | string / array<string> | opcional | wasSentByApi, wasNotSentByApi, fromMeYes, fromMeNo, isGroupYes, isGroupNo. |
addUrlEvents | boolean / string / integer / null | opcional | Deve ser false. |
addUrlTypesMessages | boolean / string / integer / null | opcional | Deve ser false. |
secret | string | opcional | Segredo de assinatura do webhook; até 256 ASCII sem espaços. Nunca é devolvido. Comprimento máximo: 256. Somente na requisição; não é devolvido |
Pelo menos uma destas combinações deve ser válida:
action;action: Valores:"delete","inherit"url,events
Respostas
Cadastrar, atualizar ou remover webhook
Variante 1
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
registered | boolean | obrigatório | — |
id | string | opcional | Formato: uuid |
url | string | opcional | — |
events | array<string> | opcional | — |
enabled | boolean | opcional | — |
excludeMessages | array / null | opcional | — |
hasSecret | boolean | opcional | — |
secretSealed | boolean | opcional | — |
createdAt | string | opcional | RFC 3339. Formato: date-time |
updatedAt | string | opcional | RFC 3339. Formato: date-time |
deliveryStatus | object | opcional | Modelo: DeliveryStatus. |
ignoredEvents | array<string> | opcional | — |
webhooks | array<object> | opcional | — |
inheritedGlobal | boolean | opcional | Indica que a inscrição segue o webhook global do servidor. |
Variante 2
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
success | boolean | obrigatório | Valores: true |
deleted | boolean | obrigatório | Valores: true |
invalid_url/event/events/exclude/secret, invalid_action ou unsupported_option.
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
error | string | obrigatório | — |
message | string | opcional | — |
messageid | string | opcional | ID para reconciliação quando o resultado é ambíguo. |
messageId | string | opcional | — |
id | string | opcional | — |
provider_code | integer | opcional | — |
error_key | string | opcional | — |
error_source | string | opcional | — |
details | object | opcional | — |
instance | object | opcional | Modelo: Instance. |
unauthorized: header ausente, inválido ou duplicado. Bearer/query/instancekey não substituem admintoken/token.
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
error | string | obrigatório | — |
message | string | opcional | — |
messageid | string | opcional | ID para reconciliação quando o resultado é ambíguo. |
messageId | string | opcional | — |
id | string | opcional | — |
provider_code | integer | opcional | — |
error_key | string | opcional | — |
error_source | string | opcional | — |
details | object | opcional | — |
instance | object | opcional | Modelo: Instance. |
instance_not_found.
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
error | string | obrigatório | — |
message | string | opcional | — |
messageid | string | opcional | ID para reconciliação quando o resultado é ambíguo. |
messageId | string | opcional | — |
id | string | opcional | — |
provider_code | integer | opcional | — |
error_key | string | opcional | — |
error_source | string | opcional | — |
details | object | opcional | — |
instance | object | opcional | Modelo: Instance. |
storage_unavailable (Retry-After=5). Algumas rotas também retornam 502 por falha da conexão/mídia; consultar error.
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
error | string | obrigatório | — |
message | string | opcional | — |
messageid | string | opcional | ID para reconciliação quando o resultado é ambíguo. |
messageId | string | opcional | — |
id | string | opcional | — |
provider_code | integer | opcional | — |
error_key | string | opcional | — |
error_source | string | opcional | — |
details | object | opcional | — |
instance | object | opcional | Modelo: Instance. |
webhooks_disabled.
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
error | string | obrigatório | — |
message | string | opcional | — |
messageid | string | opcional | ID para reconciliação quando o resultado é ambíguo. |
messageId | string | opcional | — |
id | string | opcional | — |
provider_code | integer | opcional | — |
error_key | string | opcional | — |
error_source | string | opcional | — |
details | object | opcional | — |
instance | object | opcional | Modelo: Instance. |
Falha; usar HTTP status e error. 404 rota inexistente; 405 método inválido com Allow. Ver catálogo no guia de integração.
| Campo | Tipo | Presença | Descrição |
|---|---|---|---|
error | string | obrigatório | — |
message | string | opcional | — |
messageid | string | opcional | ID para reconciliação quando o resultado é ambíguo. |
messageId | string | opcional | — |
id | string | opcional | — |
provider_code | integer | opcional | — |
error_key | string | opcional | — |
error_source | string | opcional | — |
details | object | opcional | — |
instance | object | opcional | Modelo: Instance. |