Webhooks — gerenciar pela API

⛔ O secret em texto puro aparece UMA ÚNICA VEZ, na resposta da criação. Nunca mais — não vem no GET, não volta no PATCH. Se perder, exclua o webhook e crie o…

{
  "id": "3c5e7a9f-1b2d-4c6e-8f0a-2b4d6f8a0c2e",
  "name": "Zapier — negócios ganhos",
  "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "events": ["deal.won", "deal.lost"],
  "status": "active",
  "secret_last4": "9f3a",
  "last_delivery_at": "2026-08-01T13:00:00.000Z",
  "last_delivery_ok": true,
  "consecutive_failures": 0,
  "auto_paused_at": null,
  "auto_pause_reason": null,
  "created_by": "1b7c9d2e-…",
  "created_at": "2026-07-15T10:00:00.000Z",
  "updated_at": "2026-08-01T13:00:00.000Z"
}

⛔ O secret em texto puro aparece UMA ÚNICA VEZ, na resposta da criação. Nunca mais — não vem no GET, não volta no PATCH. Se perder, exclua o webhook e crie outro.

Método Escopo Descrição
GET/api/webhooks webhooks:read Lista
POST/api/webhooks webhooks:write Cria (201) — única resposta com o secret
GET/api/webhooks/{id} webhooks:read Um webhook
PATCH/api/webhooks/{id} webhooks:write Edita name, url, events, status
DELETE/api/webhooks/{id} webhooks:write Exclui (204)
POST/api/webhooks/{id}/test webhooks:write Dispara entrega de teste (202). Exige corpo — veja abaixo
GET/api/webhooks/{id}/deliveries webhooks:read Histórico de entregas (paginado)
GET/api/webhooks/events webhooks:read Todos os eventos que dá pra assinar em events, com rótulo e categoria
Campo Criar Editar Regras
name obrigatório opcional 2–80
url obrigatório opcional precisa ser https://, até 500 caracteres; endereços internos e reservados são recusados
events obrigatório opcional de 1 a 50 eventos da lista disponível
status — (nasce active) opcional active ou paused. Religar zera a contagem de falhas

Criar, editar e excluir aceitam ?dry_run=true (o ensaio da criação não gera secret — ver §26.1).

O teste exige um corpo dizendo QUAL evento simular — sem ele, 400:

curl -X POST https://app.salos.com.br/api/webhooks/3c5e7a9f-.../test \
  -H "Authorization: Bearer $SALOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "deal.won" }'

A resposta 202 devolve o id da entrega, que você usa pra achá-la no histórico:

{ "data": { "delivery_id": "5f2e8b1a-7c4d-4e9f-8a3b-6d1c9e5f2a84" } }

O evento precisa ser um dos que aquele endpoint assina. A entrega de teste é enfileirada junto com as reais (mesma assinatura, mesmo timeout) e aparece no histórico com is_test: true.

Testar um destino quebrado não desliga o seu webhook de produção. Falha em entrega de teste é tentativa única, nunca reagendada, e não soma na contagem de falhas consecutivas.

⛔ O teste não tem ensaio. Disparar a entrega É o teste — por isso a rota recusa qualquer parâmetro de endereço com 400, inclusive ?dry_run=true (senão quem usa o ensaio no resto da API dispararia uma entrega de verdade achando que só estava conferindo).

Histórico de entregas (GET/api/webhooks/{id}/deliveries, mais recentes primeiro, paginado):

{
  "id": "5f2e8b1a-7c4d-4e9f-8a3b-6d1c9e5f2a84",
  "endpoint_id": "3c5e7a9f-1b2d-4c6e-8f0a-2b4d6f8a0c2e",
  "event": "deal.won",
  "status": "success",
  "http_status": 200,
  "attempts": 1,
  "request_body": "{\"id\":\"5f2e8b1a-…\",\"event\":\"deal.won\",…}",
  "response_preview": "ok",
  "is_test": false,
  "created_at": "2026-08-01T13:00:00.000Z"
}

status é pending (ainda tentando), success ou failed. request_body é o corpo exato que foi enviado; response_preview é o começo do que o seu servidor respondeu. Entregas do card "Acionar webhook" de uma automação aparecem aqui com event: "automation.webhook_triggered".

Lista de eventos (GET/api/webhooks/events): { "data": [ { "id": "deal.won", "label": "…", "category": "negocios" } ], "pagination": { "next_cursor": null } } — vem inteira, sem paginar.

Erro Código
url que não é https://, ou aponta para endereço interno 400
Evento fora da lista disponível (GET/api/webhooks/events) — a mensagem cita o evento recusado 400
Limite de 20 webhooks por conta 409
Testar um evento que aquele webhook não assina 400
Testar um webhook pausado 400