# Configurar, desativar ou herdar webhook por ID

`POST /v1/instances/{id}/webhook`

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`

## Resposta 200

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](https://wpp.atendro.cloud/docs/modelos/delivery-status.md). |
| `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` |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "registered": true,
  "url": "https://seu-atendro.example/webhooks/atendrozap",
  "events": [
    "connection",
    "messages"
  ],
  "enabled": true,
  "hasSecret": true,
  "inheritedGlobal": true
}
```

## Resposta 400

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](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 401

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](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "unauthorized"
}
```

## Resposta 404

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](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta 502

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](https://wpp.atendro.cloud/docs/modelos/instance.md). |

Exemplo ilustrativo, com valores sintéticos:

```json
{
  "error": "storage_unavailable"
}
```

## Resposta 503

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](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Resposta default

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](https://wpp.atendro.cloud/docs/modelos/instance.md). |

## Exemplos de requisição

Defina as variáveis no ambiente privado e substitua os dados sintéticos antes de usar. Os exemplos não executam operações nesta página.

### cURL

```sh
curl --request POST "$ATENDROZAP_URL/v1/instances/${ID}/webhook" \
  --header "admintoken: $ATENDROZAP_ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "action": "inherit"
}'
```

### JavaScript

```javascript
const baseUrl = process.env.ATENDROZAP_URL;
let path = "/v1/instances/{id}/webhook";
path = path.replace("{id}", encodeURIComponent(process.env.ID));
const url = new URL(path, baseUrl);

const response = await fetch(url, {
  method: "POST",
  headers: {
    "admintoken": process.env.ATENDROZAP_ADMIN_TOKEN,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "action": "inherit"
  }),
});

if (!response.ok) {
  throw new Error(`AtendroZAP: HTTP ${response.status}`);
}
const result = await response.json();
```

## Relacionados

- [Webhooks e eventos](https://wpp.atendro.cloud/docs/api/webhooks.md)
- [Autenticação](https://wpp.atendro.cloud/docs/guias/autenticacao.md)
- [Erros e idempotência](https://wpp.atendro.cloud/docs/guias/erros-e-idempotencia.md)