Gerenciamento de webhooks

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

Criar um webhook

cURL

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 (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:

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

Listar webhooks

cURL

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

cURL

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

Editar um webhook

cURL

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

cURL

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:

cURL

# 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

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.

Reativação após desabilitação

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

cURL

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.

​Criar um webhook

​Listar webhooks

​Obter um webhook específico

​Editar um webhook

​Remover um webhook

​Habilitar e desabilitar

​Política de retry

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

Criar um webhook

Listar webhooks

Obter um webhook específico

Editar um webhook

Remover um webhook

Habilitar e desabilitar

Política de retry

Reativação após desabilitação