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 |