Cadastrar, alterar e remover endpoints, ler o log de entregas, reenviar, disparar eventos de teste e escutar em tempo real por SSE, com curl, steel CLI e SDK.
Nesta página
Tudo o que a tela Ajustes › Webhooks faz também dá para fazer
pela API v1. Esta página cobre as chamadas; como receber e conferir as
entregas está em Receber os webhooks do Steel, e o
formato de cada evento no Catálogo de eventos.
As rotas de webhooks não dependem de módulo, mas exigem um token pessoal de
dono ou administrador do workspace; o workspace é o do token. As
alterações exigem api:write; sem ele, a resposta é
403 API_TOKEN_SCOPE_REQUIRED, como nas outras rotas da v1. Além do limite de cada token, estas rotas contam 100
requisições a cada 60 segundos por token.
O secretsó volta nesta resposta: guarde na hora. Depois, só pela tela
(Revelar segredo). secretHint são os quatro últimos caracteres, para
saber qual segredo está em uso.
A resposta traz data.items com os endpoints, no formato acima e sem o
segredo. Um endpoint desativado pelo Steel tem active: false,
disabledReason: "auto" e disabledAt; desativado por alguém,
disabledReason: "manual". failingSince mostra desde quando ele falha.
PATCH muda só os campos enviados. Reativar ("active": true) zera
disabledAt, disabledReason e failingSince:
Um id que não existe responde 404 WEBHOOK_ENDPOINT_NOT_FOUND.
Enviar teste
Manda um steel.ping só para aquele endpoint, na hora e numa tentativa,
mesmo se ele estiver desativado, e devolve a entrega com a resposta. Não conta
para a desativação automática.
curl -X POST "$STEEL_URL/api/v1/webhooks/endpoints/cm2whe0001/test" \
-H "Authorization: Bearer $STEEL_TOKEN"
Mais uma tentativa da mesma entrega: mesmo corpo, mesmo Steel-Webhook-Id,
timestamp e assinatura novos. Vai mesmo a um endpoint desativado. Responde
202 com a entrega já na fila.
curl -X POST "$STEEL_URL/api/v1/webhooks/deliveries/cm2dlv0042/retry" \
-H "Authorization: Bearer $STEEL_TOKEN"
Erros: 404 WEBHOOK_DELIVERY_NOT_FOUND (passou dos 30 dias ou não existe) e
404 WEBHOOK_ENDPOINT_NOT_FOUND (o endpoint foi removido).
Disparar um evento de teste
Cria um evento do tipo pedido com os dados de exemplo do
catálogo. Ele vai para quem está escutando
(steel listen) e, com endpointId, para aquele endpoint. Nunca para os
outros endpoints que assinam o tipo.
deliveries é 0 sem endpointId: só quem escuta recebe. Um tipo de módulo
fora do token responde 403; um tipo que não existe, 422.
steel trigger crm.deal.won --endpoint cm2whe0001
Escutar em tempo real (SSE)
GET /api/v1/webhooks/listen abre um stream
Server-Sent Events
com os eventos do workspace, na hora em que acontecem. É o que o steel listen
usa. Não há replay: só chega o que acontece com a conexão aberta.
?events=a,b filtra por tipo.
ready chega primeiro, com o segredo da escuta: fixo por pessoa e
workspace, diferente do segredo dos endpoints.
Cada webhook traz o corpo exato (body, como texto) e os valores dos três
cabeçalhos Steel-Webhook-* (id, timestamp, signature), assinados com
o segredo da escuta. Repasse assim, sem alterar, e a verificação do seu app
funciona igual à de produção.
: ping a cada 25 segundos mantém a conexão aberta através de proxies.
No SDK, listen() devolve um iterador que nunca lança exceção e sempre
termina com uma mensagem disconnected; reconectar fica com você:
const opened = await steel.webhooks.listen({ events: ['crm.lead.created'] })
if (!opened.ok) throw new Error(opened.error.code)
for await (const message of opened.data) {
if (message.type === 'webhook') console.log(message.event?.type, message.frame.id)
if (message.type === 'disconnected') console.warn('caiu:', message.reason)
}
Para o uso do dia a dia, prefira o steel listen --forward, que já reconecta e
repassa: veja Testar na sua máquina.
Solução de problemas
Sintoma
O que fazer
403 FORBIDDEN em toda rota de webhooks
O dono do token não é dono nem administrador do workspace
403 FORBIDDEN só em POST, PATCH e DELETE
O token é Somente ler
O secret sumiu da resposta de listagem
É assim: ele só volta na criação. Pegue de novo na tela, em Revelar segredo
curl da escuta não mostra nada até fechar
Use curl -N (sem buffer). Um proxy corporativo pode segurar SSE
steel trigger não chegou ao endpoint
Sem --endpoint, o evento de teste só vai para quem está escutando
