> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Gerenciamento de webhooks

> Como criar, editar e remover webhooks na Spedy.

Webhooks são gerenciados pelo recurso `/v1/webhooks`, autenticado com o
header `X-Api-Key` como qualquer outra chamada da API (veja
[Autenticação](/pages/start/autenticacao)). Lembre-se: o webhook é
configurado **por conta**, não por empresa — veja [Webhooks: visão
geral](/pages/webhooks/visao-geral).

## Criar um webhook

```bash cURL theme={null}
curl -X POST https://api.spedy.com.br/v1/webhooks \
  -H "X-Api-Key: sua-chave-de-api" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "invoice.status_changed",
    "url": "https://seusistema.com.br/webhooks/spedy"
  }'
```

Os dois campos são obrigatórios:

| Campo   | Descrição                                                                             |
| ------- | ------------------------------------------------------------------------------------- |
| `event` | Um dos [eventos disponíveis](/pages/webhooks/eventos-e-payload) (máx. 80 caracteres). |
| `url`   | URL HTTPS que receberá o POST com o payload do evento (máx. 200 caracteres).          |

Para assinar mais de um evento, crie um webhook para cada `event` — não há
um campo de lista de eventos por webhook.

A resposta traz o webhook criado, incluindo o `id` gerado e `enabled: true`:

```json theme={null}
{
  "id": "5f1e2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "event": "invoice.status_changed",
  "url": "https://seusistema.com.br/webhooks/spedy",
  "enabled": true
}
```

## Listar webhooks

```bash cURL theme={null}
curl "https://api.spedy.com.br/v1/webhooks?page=1&pageSize=20" \
  -H "X-Api-Key: sua-chave-de-api"
```

Aceita paginação por `page` e `pageSize`. Retorna os webhooks configurados
na conta, cada um com `id`, `event`, `url` e `enabled`.

## Obter um webhook específico

```bash cURL theme={null}
curl https://api.spedy.com.br/v1/webhooks/{id} \
  -H "X-Api-Key: sua-chave-de-api"
```

## Editar um webhook

```bash cURL theme={null}
curl -X PUT https://api.spedy.com.br/v1/webhooks/{id} \
  -H "X-Api-Key: sua-chave-de-api" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "invoice.authorized",
    "url": "https://seusistema.com.br/webhooks/spedy-v2"
  }'
```

`PUT` substitui `event` e `url` — ambos são obrigatórios no corpo, mesmo que
você só queira alterar um dos dois.

## Remover um webhook

```bash cURL theme={null}
curl -X DELETE https://api.spedy.com.br/v1/webhooks/{id} \
  -H "X-Api-Key: sua-chave-de-api"
```

## Habilitar e desabilitar

Além do CRUD, dois endpoints controlam o estado `enabled` sem precisar
reenviar `event`/`url`:

```bash cURL theme={null}
# Desabilitar
curl -X PUT https://api.spedy.com.br/v1/webhooks/{id}/disable \
  -H "X-Api-Key: sua-chave-de-api"

# Habilitar
curl -X PUT https://api.spedy.com.br/v1/webhooks/{id}/enable \
  -H "X-Api-Key: sua-chave-de-api"
```

Isso é útil tanto para pausar um webhook manualmente (ex.: durante uma
manutenção no seu endpoint) quanto para reativá-lo depois de uma
desabilitação automática — veja a seção seguinte.

## Política de retry

Quando a entrega de um webhook falha (endpoint indisponível, timeout, HTTP
5xx), a Spedy executa até **5 retentativas** com intervalos crescentes:

| Tentativa | Intervalo após a falha anterior |
| --------- | ------------------------------- |
| 1ª        | 5 minutos                       |
| 2ª        | 30 minutos                      |
| 3ª        | 1 hora                          |
| 4ª        | 4 horas                         |
| 5ª        | 16 horas                        |

<Warning>
  Após 5 falhas consecutivas, o webhook é **desabilitado automaticamente**
  (`enabled: false`). Nenhum novo evento é enviado para ele até que seja
  reativado — eventos que ocorrerem nesse meio-tempo **não são
  reenviados** quando você reabilita o webhook.
</Warning>

## Reativação após desabilitação

Para reativar um webhook desabilitado (seja manualmente ou por esgotamento
de retentativas), chame:

```bash cURL theme={null}
curl -X PUT https://api.spedy.com.br/v1/webhooks/{id}/enable \
  -H "X-Api-Key: sua-chave-de-api"
```

Como eventos perdidos durante o período desabilitado não são reenviados,
reconcilie o estado das notas afetadas consultando os endpoints de leitura
(`GET /v1/service-invoices`, `GET /v1/product-invoices`, `GET
/v1/consumer-invoices`) antes ou depois de reabilitar.