# API de Webhooks

Webhooks permitem que a plataforma notifique seus outros sistemas no momento em que algo acontece — um novo contato, uma resposta, um agendamento marcado e muito mais. Esta API gerencia as próprias **assinaturas**: quais URLs recebem quais eventos. Para saber como receber e verificar os payloads que seu endpoint recebe, consulte [Webhooks](../integrations/webhooks.md).

Todos os caminhos abaixo são relativos à URL base da API:

```
https://api.youraiconnector.com/v1
```

Cada solicitação deve ser autenticada. Consulte [Autenticação](authentication.md) para os quatro métodos aceitos. Os exemplos aqui usam o cabeçalho `X-API-Key` (e uma forma de parâmetro de consulta para cURL).

::: note
**Nota:** Webhooks devem estar habilitados para sua conta. Se não estiverem, estes endpoints retornarão um `403`.
:::


---

## Como as assinaturas são endereçadas

Cada assinatura tem um `id` e um `name` opcional. Qualquer um deles pode ser usado como o `{webhookId}` no caminho para atualizar, excluir, testar, verificar a integridade e reabilitar.

> **Prefira o nome.** Os IDs de assinatura são posicionais, portanto, podem mudar após a exclusão de outra assinatura. Se você definir um `name` estável ao criar uma assinatura, enderece-a pelo nome para evitar surpresas.

---

## Listar assinaturas

`GET /webhooks`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Resposta**

```json
{
  "success": true,
  "webhooks": [
    {
      "id": "0",
      "name": "Order updates hook",
      "url": "https://hooks.example.com/incoming",
      "subscribed_to": ["Contact Created", "Replies"],
      "subscribed_to_tags": [],
      "created_at": "2026-06-09T12:00:00.000Z",
      "signing_enabled": true,
      "signing_secret_created_at": "2026-07-15T09:30:00.000Z",
      "retries_enabled": true,
      "enabled": true,
      "apply_to_sub_accounts": false
    }
  ]
}
```

`signing_enabled` e `retries_enabled` são opções de adesão por assinatura, ambas desativadas a menos que você as ative. Consulte [Payloads assinados](#signed-payloads) e [Tentativas de reenvio](#retries).

`apply_to_sub_accounts` é a opção de adesão à herança de agência — veja [Uma assinatura para todas as contas de cliente](#one-subscription-for-all-client-accounts-agencies). Desativado por padrão e inerte em contas que não possuem contas de cliente.

`enabled` é o interruptor liga/desliga da assinatura — veja [Desativando uma assinatura](#switching-a-subscription-off). Assinaturas desativadas ainda são listadas aqui.

O segredo de assinatura em si nunca é incluído aqui — leia-o a partir de [`GET /webhooks/{id}/signing-secret`](#read-the-signing-secret).

---

## Listar tipos de eventos assináveis

Retorna as strings exatas que você pode usar em `subscribed_to`. Use isso para descobrir nomes de eventos válidos em vez de codificá-los diretamente.

`GET /webhooks/events`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks/events" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/events", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/events",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Resposta**

A resposta é `{"success": true, "events": [...]}`, onde `events` atualmente contém 22 strings exatas: Contact Created, Human Alerted, Appointment Booked, Replies, Reads, Deliveries, Credits Spent, Credits Recharged, Low Credit Balance, Contact Paused, Contact Do Not Disturb, Contact Unarchived, New Message, Contact Resumed, Chat Concluded, Task Created, Task Updated, Task Completed, Daily Summary Created, Channel Connected, Broadcast Started e Broadcast Completed (Channel Connected é aceito em `subscribed_to`, mas nada o emite atualmente, então não crie nada baseado nele).

Para saber o que cada evento significa e o código `event` que ele envia no payload, veja [Os 22 Eventos de Webhook](../integrations/webhooks.md#the-22-webhook-events). Este endpoint é a lista oficial a qualquer momento — leia-a dinamicamente em vez de codificar os nomes manualmente.

---

## Criar uma assinatura

`POST /webhooks`

| Campo | Obrigatório | Descrição |
|---|---|---|
| `url` | Sim | URL HTTPS que receberá os payloads de eventos via `POST`. Deve ser publicamente acessível. |
| `subscribed_to` | Sim | Um array não vazio de nomes de eventos (veja `/webhooks/events`). |
| `name` | Não | Um nome de exibição. Também utilizável como `{webhookId}` posteriormente. O padrão é um nome com carimbo de data/hora. |
| `subscribed_to_tags` | Não | IDs de tags que restringem quais tags produzem uma notificação de resumo de conversa. Isso não limita os eventos da assinatura a essas tags — para receber uma solicitação quando uma tag específica for aplicada, defina uma URL de webhook nessa tag na aba **Tags** do agente (ou campanha). |
| `retries_enabled` | Não | Booleano, o padrão é `false`. Opte por [tentativas de reenvio](#retries) de entregas falhas. |
| `generate_signing_secret` | Não | Booleano, o padrão é `false`. Gere um [segredo de assinatura](#signed-payloads) HMAC com a assinatura. O segredo é retornado uma vez, como um `signing_secret` de nível superior na resposta. |
| `enabled` | Não | Booleano, o padrão é `true`. Passe `false` para criar a assinatura desativada. Veja [Desativando uma assinatura](#switching-a-subscription-off). |
| `apply_to_sub_accounts` | Não | Booleano, o padrão é `false`. Em uma conta de agência, `true` faz com que esta assinatura também receba eventos de todas as contas de cliente — veja [Uma assinatura para todas as contas de cliente](#one-subscription-for-all-client-accounts-agencies). |

> **Regras de URL:** A URL deve usar `https://` e ser acessível publicamente. `http://` simples, `localhost`, endereços de rede privada e endereços internos da plataforma são rejeitados com um `400`.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Order updates hook"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Order updates hook",
  }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Order updates hook",
    },
)
data = res.json()
```

**Resposta**

```json
{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}
```

---

## Atualizar uma assinatura

Forneça pelo menos um dos campos `url`, `subscribed_to`, `name`, `subscribed_to_tags`, `retries_enabled`, `enabled` ou `apply_to_sub_accounts`. Campos omitidos mantêm seus valores atuais. `subscribed_to` e `subscribed_to_tags` são substituições, não mesclagens.

`PUT /webhooks/{webhookId}`

> Atualizar uma assinatura nunca altera seu segredo de assinatura — gerencie isso através das [rotas de segredo de assinatura](#signed-payloads).

> Quando a URL é alterada, a entrega para a nova URL é reativada automaticamente, dando a um endpoint que falhou anteriormente um novo começo.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/Order%20updates%20hook" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"]
  }'
```

**JavaScript**

```javascript
const res = await fetch(
  `https://api.youraiconnector.com/v1/webhooks/${encodeURIComponent("Order updates hook")}`,
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://hooks.example.com/v2/incoming",
      subscribed_to: ["Replies", "Chat Concluded"],
    }),
  }
);
const data = await res.json();
```

**Python**

```python
import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/webhooks/Order updates hook",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "url": "https://hooks.example.com/v2/incoming",
        "subscribed_to": ["Replies", "Chat Concluded"],
    },
)
data = res.json()
```

**Resposta**

```json
{
  "success": true,
  "webhook_id": "0",
  "webhook": {
    "id": "0",
    "name": "Order updates hook",
    "url": "https://hooks.example.com/v2/incoming",
    "subscribed_to": ["Replies", "Chat Concluded"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}
```

Um id ou nome desconhecido retorna `404` com `{ "success": false, "error": "Webhook not found" }`.

---

## Excluir uma assinatura

Remove a assinatura para que sua URL pare de receber payloads. Seus contadores de integridade de entrega são redefinidos, portanto, adicionar a mesma URL novamente mais tarde começa com um registro limpo.

`DELETE /webhooks/{webhookId}`

**cURL**

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0", {
  method: "DELETE",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/webhooks/0",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Resposta**

```json
{
  "success": true
}
```

---

## Enviar um payload de teste

Envia um payload de amostra para a URL da assinatura para que você possa verificar seu receptor de ponta a ponta. Opcionalmente, passe um `event` para controlar qual tipo de evento a amostra simula. Entregas de teste nunca afetam os contadores de integridade da assinatura.

`POST /webhooks/{webhookId}/test`

A resposta sempre retorna `200` e relata o resultado com um sinalizador `delivered` — um teste com falha **não** retorna um status de erro. Quando `delivered` é `false`, a resposta inclui os detalhes da falha.

| Campo | Obrigatório | Descrição |
|---|---|---|
| `event` | Não | Tipo de evento a simular (deve ser um dos `/webhooks/events`). O padrão é um evento de entrega. |

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/test?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "Contact Created" }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/test", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ event: "Contact Created" }),
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/test",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"event": "Contact Created"},
)
data = res.json()
```

**Resposta** (entregue)

```json
{
  "success": true,
  "webhook_id": "0",
  "delivered": true
}
```

**Resposta** (falhou)

```json
{
  "success": true,
  "webhook_id": "0",
  "delivered": false,
  "failure_type": "permanent",
  "status_code": 404,
  "error_message": "Request failed with status code 404"
}
```

`failure_type` é um de `permanent`, `temporary`, `timeout`, `network` ou `unknown`.

---

## Verificar integridade da entrega

Retorna o registro de integridade da entrega para a URL da assinatura: quantas entregas foram bem-sucedidas e falharam, se a entrega está pausada no momento após falhas repetidas e os detalhes da falha mais recente. Retorna `"health": null` quando nenhuma entrega foi tentada ainda.

`GET /webhooks/{webhookId}/health`

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/webhooks/0/health" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/health", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/webhooks/0/health",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Resposta**

```json
{
  "success": true,
  "webhook_id": "0",
  "url": "https://hooks.example.com/incoming",
  "health": {
    "consecutive_failures": 0,
    "total_failures": 2,
    "total_successes": 120,
    "is_disabled": false,
    "disabled_at": null,
    "disabled_reason": null,
    "last_failure": null,
    "last_success_at": "2026-06-09T12:00:00.000Z",
    "created_at": "2026-05-01T08:00:00.000Z",
    "updated_at": "2026-06-09T12:00:00.000Z"
  }
}
```

Quando `is_disabled` é `true`, a entrega para a URL foi pausada automaticamente após falhas repetidas. Corrija seu receptor e, em seguida, reative-o (abaixo).

---

## Reativar entrega

Resume a entrega para um webhook cuja URL foi pausada automaticamente após falhas repetidas. Isso redefine o sinalizador de pausa e os contadores de falha, mas **não** tenta uma entrega — use o endpoint de teste posteriormente para confirmar se seu receptor está íntegro novamente.

`POST /webhooks/{webhookId}/reenable`

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/reenable?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/reenable", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/webhooks/0/reenable",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

**Resposta**

```json
{
  "success": true,
  "webhook_id": "0"
}
```

---

## Desativando uma assinatura

`enabled` é o próprio interruptor liga/desliga da assinatura. Desativá-lo interrompe as entregas enquanto mantém a URL, a lista de eventos e o segredo de assinatura intactos.

```bash
# Off
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Back on
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

- **Ausente significa ligado.** Uma assinatura criada antes da existência deste campo não tem valor `enabled` armazenado e realiza entregas normalmente. `GET /webhooks` sempre relata um booleano concreto.
- Assinaturas desativadas **ainda são listadas** por `GET /webhooks` — é assim que você as encontra para reativá-las.
- Uma [tentativa de reenvio](#retries) enfileirada antes da desativação não é retomada: a tentativa de reenvio lê a assinatura novamente no momento do envio e é descartada se ela estiver desativada.
- Nada suprimido enquanto desativado é reproduzido quando você a reativa.

> Distinto da desativação automática após falhas repetidas, que é relatada por [`GET /webhooks/{id}/health`](#check-delivery-health) como `is_disabled` e limpa com [`POST /webhooks/{id}/reenable`](#re-enable-delivery). `enabled` é o interruptor da conta; `is_disabled` é o nosso. Nenhum substitui o outro — uma assinatura deve estar ligada e não desativada automaticamente para realizar entregas.

---

## Uma assinatura para todas as contas de cliente (agências)

Em uma conta de agência, defina `apply_to_sub_accounts: true` em uma assinatura (no momento da criação ou via `PUT`) e ela também receberá eventos que ocorrem em cada uma das contas de cliente da agência — um único endpoint cobre toda a agência, em vez de recriar a assinatura em cada conta de cliente.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apply_to_sub_accounts": true}'
```

Como ele se comporta:

- **O bloco `user` diferencia as contas.** O bloco `user` de cada payload identifica a conta em que o evento realmente ocorreu, para que seu receptor possa rotear por cliente.
- **As próprias configurações da assinatura da agência se aplicam em toda parte.** Sua lista de eventos, [segredo de assinatura](#signed-payloads) e opção de [tentativa de reenvio](#retries) também são usados para as entregas herdadas.
- **A própria assinatura de uma conta de cliente para a mesma URL tem prioridade.** Se uma conta de cliente tiver sua própria assinatura apontando para a mesma URL, ela será usada para os eventos daquela conta — o mesmo evento nunca é entregue duas vezes para um único endpoint.
- **Contas de cliente não veem isso.** Assinaturas herdadas não aparecem na lista de webhooks da própria conta de cliente, e o cliente não pode desativá-las — apenas a agência as gerencia.
- **A integridade da entrega é rastreada por conta de cliente.** Um endpoint que continua falhando é desativado automaticamente para a conta cujas entregas falharam, não para toda a agência.
- **`subscribed_to_tags` não é herdado.** A lista de tags faz referência às próprias tags da agência, que não existem nas contas de cliente — a restrição de resumo de conversa aplica-se apenas aos eventos da própria agência.
- **Inerte em outros lugares.** Em uma conta sem contas de cliente, o sinalizador é armazenado corretamente e não faz nada.

---

## Cabeçalhos em cada entrega

Estes três cabeçalhos são enviados em cada entrega, independentemente de a assinatura estar assinada ou não:

| Cabeçalho | Significado |
|---|---|
| `X-Webhook-Delivery` | ID estável para o evento lógico. Idêntico entre tentativas de reenvio — use para deduplicação. |
| `X-Webhook-Attempt` | Número da tentativa (base 1). |
| `X-Webhook-Event` | O nome do evento. |

---

## Payloads assinados

A assinatura é opcional, desativada por padrão e definida por assinatura. Quando uma assinatura possui um segredo de assinatura, cada entrega carrega dois cabeçalhos adicionais além dos três enviados em cada entrega (`X-Webhook-Delivery`, `X-Webhook-Attempt` e `X-Webhook-Event`):

| Cabeçalho | Significado |
|---|---|
| `X-Webhook-Signature` | `v1=<hex>` — HMAC-SHA256 da string `"<timestamp>.<raw request body>"`, codificada com o segredo de assinatura por webhook que você gera e rotaciona em `GET/POST/DELETE /v1/webhooks/{webhookId}/signing-secret`. |
| `X-Webhook-Timestamp` | Horário de envio, em segundos Unix. Vinculado à assinatura, portanto, não pode ser alterado independentemente. |

Para verificar, recalcule o HMAC-SHA256 sobre o corpo bruto com seu segredo e compare-o com o cabeçalho. Verifique em relação ao corpo da solicitação **bruto**. A re-serialização do JSON analisado altera os bytes e quebra a comparação. Rejeite entregas cujo carimbo de data/hora esteja fora de uma janela de validade (300s é um padrão razoável) para evitar repetição, e compare com uma função de tempo constante (timing-safe).

Consulte [Payloads assinados](../integrations/webhooks.md#signed-payloads-verifying-a-webhook-really-came-from-us) para exemplos completos de verificação em Node e Python.

> **Assinatura não é o mesmo que autenticação de API.** A API REST em si autentica com chaves de API em vez de OAuth (OAuth 2.1 existe para servidores MCP que você registra como ferramentas de bot), e ainda não existem pacotes SDK oficiais para npm ou PyPI — chame os endpoints com qualquer cliente HTTP.

### Ler o segredo de assinatura

`GET /webhooks/{id}/signing-secret`

```bash
curl "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**Resposta**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_1a2b3c...",
  "signing_secret_created_at": "2026-07-15T09:30:00.000Z"
}
```

Quando a assinatura está desativada, `signing_enabled` é `false` e `signing_secret` é `null`.

### Gerar ou rotacionar o segredo de assinatura

`POST /webhooks/{id}/signing-secret`

Cria um segredo (ativando a assinatura) ou substitui o existente. Retorna o novo segredo.

```bash
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**Resposta**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": true,
  "signing_secret": "whsec_9f8e7d...",
  "signing_secret_created_at": "2026-07-15T10:00:00.000Z"
}
```

A rotação entra em vigor imediatamente — a próxima entrega é assinada apenas com o novo segredo. Aceite ambos os segredos brevemente enquanto você implementa a alteração em um endpoint ativo.

Você também pode gerar um segredo no momento da criação passando `"generate_signing_secret": true` para `POST /webhooks`; a resposta então inclui um campo `signing_secret` de nível superior.

### Desativar assinatura

`DELETE /webhooks/{id}/signing-secret`

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
```

**Resposta**

```json
{
  "success": true,
  "webhook_id": "0",
  "signing_enabled": false
}
```

> Todas as três rotas de segredo de assinatura exigem a permissão de **edição** de Integrações, incluindo `GET` — o segredo é uma credencial que pode forjar entregas, portanto, não é exposto a funções somente leitura.

---

## Novas tentativas

Opcional, desativado por padrão e definido por assinatura através do booleano `retries_enabled` em `POST /webhooks` ou `PUT /webhooks/{id}`.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"retries_enabled": true}'
```

Quando ativado, uma entrega com falha é tentada novamente em **1m, 5m, 30m e 2h** após a primeira tentativa (cerca de 2h40m de cobertura).

- **Tentado novamente:** respostas 5xx, timeouts e falhas de conexão.
- **Não tentado novamente:** qualquer 4xx. O receptor está rejeitando a própria solicitação, portanto, repeti-la sem alterações apenas reproduz a rejeição.

As tentativas tornam possível a entrega duplicada — um endpoint que processou um evento, mas expirou antes de responder, o verá novamente. Use `X-Webhook-Delivery` para deduplicação, que é constante em todas as tentativas. É por isso que as tentativas são opcionais.

Os contadores de [delivery-health](#check-delivery-health) contam uma entrega completa, não cada tentativa: uma falha é registrada apenas uma vez quando todas as tentativas são esgotadas, portanto, ativar as novas tentativas não faz com que o gatilho de desativação automática ocorra mais cedo.

---

## Erros

Todos os erros usam o envelope padrão:

```json
{
  "success": false,
  "error": "Webhook not found"
}
```

Casos comuns: uma URL que não é permitida, um `subscribed_to` vazio/inválido ou campos ausentes retornam `400`; um id ou nome desconhecido retorna `404`; e um `403` significa que webhooks não estão habilitados para sua conta. Veja [Erros](errors-and-pagination.md) para a lista completa.

---

## Próximos passos

- [Webhooks (recebendo payloads)](../integrations/webhooks.md) — configure seu receptor e entenda o formato do payload.
- [Autenticação](authentication.md) — as quatro maneiras de autenticar uma solicitação.
- [Erros e Limites de Taxa](errors-and-pagination.md) — códigos de status e o limite de 300 req/min.