# API de Webhooks

Os webhooks permitem que a plataforma notifique os seus outros sistemas no momento em que algo acontece — um novo contacto, uma resposta, uma marcação agendada, e muito mais. Esta API gere as próprias **subscrições**: que URLs recebem que eventos. Para saber como receber e verificar os payloads que o seu endpoint recebe, consulte [Webhooks](../integrations/webhooks.md).

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

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

Todos os pedidos devem ser autenticados. Consulte [Autenticação](authentication.md) para os quatro métodos aceites. Os exemplos aqui utilizam o cabeçalho `X-API-Key` (e uma forma de parâmetro de consulta para cURL).

::: note
**Nota:** Os webhooks devem estar ativados na sua conta. Caso contrário, estes endpoints devolvem um `403`.
:::


---

## Como as subscrições são endereçadas

Cada subscrição tem um `id` e um `name` opcional. Qualquer um deles pode ser utilizado como o `{webhookId}` no caminho para atualizar, eliminar, testar, verificar o estado e reativar.

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

---

## Listar subscrições

`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 ativação por subscrição, ambas desativadas a menos que as ative. Consulte [Payloads assinados](#signed-payloads) e [Reiterações](#retries).

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

`enabled` é o interruptor de ligar/desligar da subscrição — consulte [Desligar uma subscrição](#switching-a-subscription-off). As subscrições desligadas continuam 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 subscrevíveis

Devolve as strings exatas que pode utilizar em `subscribed_to`. Utilize isto para descobrir nomes de eventos válidos em vez de os codificar 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` contém atualmente 22 cadeias de caracteres 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 é aceite em `subscribed_to`, mas nada o emite atualmente, por isso não baseie nada nele).

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

---

## Criar uma subscrição

`POST /webhooks`

| Campo | Obrigatório | Descrição |
|---|---|---|
| `url` | Sim | URL HTTPS que receberá payloads de eventos via `POST`. Deve ser publicamente acessível. |
| `subscribed_to` | Sim | Uma matriz não vazia de nomes de eventos (consulte `/webhooks/events`). |
| `name` | Não | Um nome de exibição. Também utilizável como `{webhookId}` mais tarde. Predefinido para um nome com carimbo de data/hora. |
| `subscribed_to_tags` | Não | IDs de etiquetas que restringem quais as etiquetas que produzem uma notificação de resumo de conversação. Não limita os eventos da subscrição a essas etiquetas — para obter um pedido quando uma etiqueta específica é aplicada, defina um URL de webhook nessa etiqueta no separador **Etiquetas** do agente (ou campanha). |
| `retries_enabled` | Não | Booleano, predefinido para `false`. Opte por [tentativas de reenvio](#retries) de entregas falhadas. |
| `generate_signing_secret` | Não | Booleano, predefinido para `false`. Crie um [segredo de assinatura](#signed-payloads) HMAC com a subscrição. O segredo é devolvido uma vez, como um `signing_secret` de nível superior na resposta. |
| `enabled` | Não | Booleano, predefinido para `true`. Passe `false` para criar a subscrição desativada. Consulte [Desativar uma subscrição](#switching-a-subscription-off). |
| `apply_to_sub_accounts` | Não | Booleano, predefinido para `false`. Numa conta de agência, `true` faz com que esta subscrição também receba eventos de todas as contas de cliente — consulte [Uma subscrição para todas as contas de cliente](#one-subscription-for-all-client-accounts-agencies). |

> **Regras de URL:** O URL deve utilizar `https://` e ser publicamente acessível. `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 subscrição

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

`PUT /webhooks/{webhookId}`

> Atualizar uma subscrição nunca altera o seu segredo de assinatura — faça a gestão através das [rotas de segredo de assinatura](#signed-payloads).

> Quando o URL é alterado, a entrega para o novo URL é automaticamente reativada, 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 devolve `404` com `{ "success": false, "error": "Webhook not found" }`.

---

## Eliminar uma subscrição

Remove a subscrição para que o seu URL deixe de receber payloads. Os seus contadores de estado de entrega são reiniciados, pelo que adicionar novamente o mesmo URL mais tarde começa com um registo 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 o URL da subscrição para que possa verificar o seu recetor de ponta a ponta. Opcionalmente, passe um `event` para controlar que tipo de evento a amostra simula. As entregas de teste nunca afetam os contadores de estado da subscrição.

`POST /webhooks/{webhookId}/test`

A resposta devolve sempre `200` e comunica o resultado com um sinalizador `delivered` — um teste falhado **não** devolve um estado 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 de `/webhooks/events`). Por predefinição, utiliza 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 o estado da entrega

Devolve o registo do estado da entrega para o URL da subscrição: quantas entregas foram bem-sucedidas e falharam, se a entrega está atualmente pausada após falhas repetidas e os detalhes da falha mais recente. Devolve `"health": null` quando ainda não foram tentadas entregas.

`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 o URL foi pausada automaticamente após falhas repetidas. Corrija o seu recetor e, em seguida, reative-o (abaixo).

---

## Reativar a entrega

Retoma a entrega para um webhook cujo URL foi pausado automaticamente após falhas repetidas. Isto repõe o sinalizador de pausa e os contadores de falhas, mas **não** tenta uma entrega — utilize o endpoint de teste posteriormente para confirmar que o seu recetor está novamente operacional.

`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"
}
```

---

## Desligar uma subscrição

`enabled` é o próprio interruptor de ligar/desligar da subscrição. Desligá-lo interrompe as entregas, mantendo intactos o URL, a lista de eventos e o segredo de assinatura.

```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 subscrição criada antes da existência deste campo não tem nenhum valor `enabled` armazenado e efetua entregas normalmente. `GET /webhooks` reporta sempre um booleano concreto.
- As subscrições desligadas **continuam listadas** por `GET /webhooks` — é assim que as encontra para as voltar a ligar.
- Uma [repetição](#retries) colocada na fila antes de desligar não é retomada: a repetição volta a ler a subscrição no momento do envio e é descartada se esta estiver desligada.
- Nada do que foi suprimido enquanto estava desligado é reproduzido quando a volta a ligar.

> Distinto da desativação automática após falhas repetidas, que é reportada 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 subscrição tem de estar ligada e não desativada automaticamente para efetuar entregas.

---

## Uma subscrição para todas as contas de cliente (agências)

Numa conta de agência, defina `apply_to_sub_accounts: true` numa subscrição (no momento da criação ou via `PUT`) e esta também receberá eventos que ocorrem em cada uma das contas de cliente da agência — um endpoint cobre toda a agência, em vez de recriar a subscrição 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 funciona:

- **O bloco `user` distingue as contas.** O bloco `user` de cada payload identifica a conta onde o evento realmente ocorreu, para que o seu recetor possa encaminhar por cliente.
- **As definições da própria subscrição da agência aplicam-se em todo o lado.** A sua lista de eventos, [segredo de assinatura](#signed-payloads) e opção de [tentativa de reenvio](#retries) são também utilizados para as entregas herdadas.
- **A subscrição da própria conta de cliente para o mesmo URL tem prioridade.** Se uma conta de cliente tiver a sua própria subscrição a apontar para o mesmo URL, essa é utilizada para os eventos dessa conta — o mesmo evento nunca é entregue duas vezes ao mesmo endpoint.
- **As contas de cliente não a veem.** As subscrições herdadas não aparecem na lista de webhooks da própria conta de cliente e o cliente não as pode desativar — apenas a agência as gere.
- **O estado da entrega é monitorizado por conta de cliente.** Um endpoint que continua a falhar é automaticamente desativado para a conta cujas entregas falharam, não para toda a agência.
- **`subscribed_to_tags` não é herdado.** A lista de etiquetas refere-se às etiquetas da própria agência, que não existem nas contas de cliente — a restrição de resumo de conversação aplica-se apenas aos eventos da própria agência.
- **Inerte noutros locais.** Numa 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 subscrição 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 — utilize-o para deduplicação. |
| `X-Webhook-Attempt` | Número da tentativa, começando em 1. |
| `X-Webhook-Event` | O nome do evento. |

---

## Payloads assinados

A assinatura é opcional, desativada por padrão e definida por subscrição. Quando uma subscrição tem um segredo de assinatura, cada entrega transporta mais dois cabeçalhos além dos três enviados em todas as entregas (`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>"`, com a chave do segredo de assinatura por webhook que cria e renova em `GET/POST/DELETE /v1/webhooks/{webhookId}/signing-secret`. |
| `X-Webhook-Timestamp` | Hora de envio, em segundos Unix. Vinculada à assinatura, pelo que não pode ser alterada independentemente. |

Para verificar, recalcule o HMAC-SHA256 sobre o corpo bruto (raw body) com o seu segredo e compare-o com o cabeçalho. Verifique contra o corpo do pedido **bruto**. A re-serialização de JSON analisado altera os bytes e quebra a comparação. Rejeite entregas cujo carimbo de data/hora esteja fora de uma janela de frescura (300s é um padrão razoável) para evitar repetições, e compare com uma função segura contra ataques de temporização (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.

> **A assinatura não é o mesmo que a autenticação da API.** A própria API REST autentica-se com chaves de API em vez de OAuth (o OAuth 2.1 existe para servidores MCP que regista 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 rodar o segredo de assinatura

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

Cria um segredo (ativando a assinatura) ou substitui o existente. Devolve 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 entrega seguinte é assinada apenas com o novo segredo. Aceite ambos os segredos brevemente enquanto implementa a alteração num endpoint em produção.

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

### Desativar a 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 segredos de assinatura requerem a permissão de **edição** de integrações, incluindo a `GET` — o segredo é uma credencial que pode falsificar entregas, pelo que não é exposto a funções de apenas leitura.

---

## Repetições

Opcional, desativado por predefinição e definido por subscrição 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 falhada é repetida após **1m, 5m, 30m e 2h** da primeira tentativa (cerca de 2h40m de cobertura).

- **Repetido:** respostas 5xx, timeouts e falhas de ligação.
- **Não repetido:** qualquer 4xx. O recetor está a rejeitar o próprio pedido, pelo que repeti-lo sem alterações apenas reproduz a rejeição.

As tentativas de reenvio tornam possível a entrega duplicada — um endpoint que processou um evento, mas cujo tempo limite expirou antes de responder, irá recebê-lo novamente. Utilize `X-Webhook-Delivery` para a desduplicação, uma vez que este é constante em todas as tentativas. É por este motivo que as tentativas de reenvio são opcionais.

Os contadores de [delivery-health](#check-delivery-health) contam uma entrega completa, não cada tentativa: uma falha é registada apenas uma vez quando todas as repetições são esgotadas, pelo que ativar as repetições não faz com que o gatilho de desativação automática seja acionado mais cedo.

---

## Erros

Todos os erros utilizam o envelope padrão:

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

Casos comuns: um URL que não é permitido, um `subscribed_to` vazio/inválido ou campos em falta devolvem `400`; um id ou nome desconhecido devolve `404`; e um `403` significa que os webhooks não estão ativados para a sua conta. Consulte [Erros](errors-and-pagination.md) para a lista completa.

---

## Próximos passos

- [Webhooks (receção de payloads)](../integrations/webhooks.md) — configure o seu recetor e compreenda a estrutura do payload.
- [Autenticação](authentication.md) — as quatro formas de autenticar um pedido.
- [Erros e Limites de Taxa](errors-and-pagination.md) — códigos de estado e o limite de 300 pedidos/min.