DocsAPI abrir plataformaEndpoint Webhook

Endpoint Webhook

Gatilho de workflow + resposta de aprovação (POST + GET one-click link).

Endpoint Webhook é usado para "eventos ativos de impulso de sistemas externos". Duas categorias: gatilho de workflow (sistema externo empurra dados → puxa execução de workflow) e callback de aprovação (sistema externo empurra decisão → completa passo manual aprovação).

1. Activação do workflow

POST /api/webhooks/{webhookId}/trigger
Autenticação: Chave API (Bearer / X- API- Key / ? api key) · Scope: WEBHOOK_TRIGGER

Primeiro crie um Webhook no console: ligue-o ao workflow alvo e escolha uma API Key com o escopo WEBHOOK TRIGGER. Um sistema externo então POSTS um objeto JSON (até 1 MB) para o URL gatilho, e os campos de nível superior da carga útil mapeiam para variáveis de workflow através do mapeamento variável ou por nomes correspondentes.

Para as etapas completas de criação, um exemplo de trigger curl, regras de mapeamento variável, a tabela de código de erro e o modo de compatibilidade HMAC, veja Activar um workflow através do WebhookEsta página cobre apenas o contrato de finalização em plataforma aberta.

Limites de permissão

verificação dupla

Um Webhook está ligado a um apiKeyId na criação. No gatilho, a Chave resolvida a partir do token de requisição deve ser exatamente a encadernada (id da chave idêntica), e a Chave e o Webhook devem pertencer à mesma conta. Isso garante que mesmo que uma chave com o escopo WEBHOOK TRIGGER vaze, ela só pode ativar os Webhooks explicitamente ligados a ele, nem os workflows de mais ninguém. Um Webhook ligado a uma API Key não aceita mais assinaturas HMAC.

2. Resposta da aprovação (método POST)

POST /api/webhook-trigger/approval
Autenticação: API Key (Bearer) · Scope: APPROVAL_RESPOND

Usado para submeter uma decisão de aprovação de um sistema externo (lógica de automação, bot Slack, e-mail-resply handling, etc.). O corpo de solicitação está a 64 KB.

bash

curl -X POST https://braidrun.com/api/webhook-trigger/approval \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "approvalId": "<approval-id>",
    "decision": "approve",
    "comment": "Approved by CFO via Slack"
  }'

Resposta bem sucedida:

json

{
  "ok": true,
  "approvalId": "<approval-id>",
  "decision": "approve"
}

Campos de solicitação

Campo	Tipo	Designação das mercadorias
`approvalId`	string	Obter de manual aprovação passo evento/lista de aprovação/modelo de notificação
`decision`	string	"aprovar" ou "rejeitar" (caso não sensível)
`comment`	string	Opcional, registado no histórico de aprovação

Respostas de erro

código do estado	significado
`400`	decisão não é aprovar ou rejeitar
`401`	A chave API é inválida ou falta o escopo APPROVAL RESPOND
`403`	O proprietário da Chave não é um revisor autorizado para esta aprovação
`404`	A aprovação não existe ou não é visível para o proprietário da Chave
`409`	A aprovação já foi tratada e não pode ser decidida novamente
`429`	Muitos pedidos; a resposta inclui cabeçalhos Retry-After e X-RateLimit-*

3. Aprovação um clique link (método GET)

GET /api/webhook-trigger/approval/{approvalId}/{decision}?api_key=…
Autenticação: API Key (parâmetro de consulta) · Scope: APPROVAL_RESPOND

A fim de permitir que o aprovador clique em um link em e-mail/Slack/Telegram para completar a aprovação, um endpoint na forma de GET é fornecido. A resposta é uma página HTML, não JSON.

text

https://braidrun.com/api/webhook-trigger/approval/<approval-id>/approve?api_key=dyk_<id>_<secret>
https://braidrun.com/api/webhook-trigger/approval/<approval-id>/reject?api_key=dyk_<id>_<secret>&comment=Need%20more%20info

A primeira vez que um link é aberto ele só mostra uma página de confirmação; a decisão é enviada apenas quando você clica no botão de confirmação nele (que adiciona confirmar=1 para o URL). Link-preview bots em clientes de e-mail e aplicativos IM apenas obter a página de confirmação, para que eles não podem aprovar por acidente.

Você pode incorporar tais links em mensagens de notificação de aprovação, por exemplo:

markdown

## 工作流等待您批准

请审批 [发票 #1234] 的支付。

[批准](https://braidrun.com/api/webhook-trigger/approval/<approval-id>/approve?api_key=<api-key>)
[拒绝](https://braidrun.com/api/webhook-trigger/approval/<approval-id>/reject?api_key=<api-key>)

Restrições de segurança para links de um clique

Uma chave API usada para aprovação de um clique deve ter uma vida útil curta (24-72 horas recomendadas)
Âmbito é estritamente limitado à HOPROVAL RESPOND, não misturar com outras permissões
Encaminhar o link equivale a entregar a autoridade de aprovação - não publicar links de texto claros no grupo, é melhor enviá-los via mensagem privada
Em caso de fuga de ligação: Entre no console para revogar imediatamente a chave. As aprovações aprovadas/rejeitas podem ser rastreadas através do diário de auditoria.

Assinaturas HMAC (para integrações legadas)

Um Webhook sem chave de API e somente um secretKey ainda usa o modo compartilhado-secreto HMAC-SHA256 (o cabeçalho X-Webhook-Assinatura). Uma vez que você vincula uma API Key a um Webhook, o HMAC não é mais aceito — a migração é de sentido único. Para novas integrações, use o modo API Key diretamente; para os detalhes do algoritmo de assinatura e migração, consulte Activar um workflow através do Webhook.