DocsAPI Open PlatformWebhook Endpoint

Webhook Endpoint

Workflow trigger + approval response (POST + GET one-click link).

Webhook endpoint is used for "active push events from external systems". Two categories: workflow trigger (external system pushes data → pulls up workflow execution) and approval callback (external system pushes decision → completes manual_approval step).

1. Workflow Triggering

POST /api/webhooks/{webhookId}/trigger
Authentication: API Key (Bearer / X-API-Key / ?api_key) · Scope: WEBHOOK_TRIGGER

First create a Webhook in the console: bind it to the target workflow and pick an API Key with the WEBHOOK_TRIGGER scope. An external system then POSTs a JSON object (up to 1 MB) to the trigger URL, and the payload's top-level fields map to workflow variables via variableMapping or by matching names.

For the full creation steps, a trigger curl example, variable-mapping rules, the error-code table, and HMAC compatibility mode, see Trigger a workflow via Webhook. This page covers only the open-platform endpoint contract.

Permission Boundaries

Double Check

A Webhook is bound to an apiKeyId at creation. On trigger, the Key resolved from the request token must be exactly the bound one (identical key id), and the Key and the Webhook must belong to the same account. This guarantees that even if a Key with the WEBHOOK_TRIGGER scope leaks, it can only trigger the Webhooks explicitly bound to it, not anyone else's workflows. A Webhook bound to an API Key no longer accepts HMAC signatures.

2. Approval Response (POST Method)

POST /api/webhook-trigger/approval
Authentication: API Key (Bearer) · Scope: APPROVAL_RESPOND

Used to submit an approval decision from an external system (automation logic, a Slack bot, email-reply handling, etc.). The request body is capped at 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"
  }'

Successful response:

json

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

Request Fields

Field	Type	Description
`approvalId`	string	Get from manual_approval step event/approval list/notification template
`decision`	string	"approve" or "reject" (case insensitive)
`comment`	string	Optional, recorded in approval history

Error Responses

Status Code	Meaning
`400`	decision is not approve or reject
`401`	The API Key is invalid or missing the APPROVAL_RESPOND scope
`403`	The Key owner is not an authorized reviewer for this approval
`404`	The approval does not exist or is not visible to the Key owner
`409`	The approval has already been handled and cannot be decided again
`429`	Too many requests; the response includes Retry-After and X-RateLimit-* headers

3. Approval One-Click Link (GET Method)

GET /api/webhook-trigger/approval/{approvalId}/{decision}?api_key=…
Authentication: API Key (query parameter) · Scope: APPROVAL_RESPOND

In order to allow the approver to click a link in email/Slack/Telegram to complete the approval, an endpoint in the form of GET is provided. The response is an HTML page, not 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

The first time a link is opened it only shows a confirmation page; the decision is submitted only when you click the confirm button on it (which appends confirm=1 to the URL). Link-preview bots in email clients and IM apps only fetch the confirmation page, so they can't approve by accident.

You can embed such links in approval notification messages, for example:

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>)

Security constraints for one-click links

An API Key used for one-click approval should have a short lifetime (24-72 hours recommended)
Scope is strictly limited to APPROVAL_RESPOND, do not mix with other permissions
Forwarding the link is equivalent to handing over the approval authority - do not post clear text links in the group, it is best to send them via private message
In case of link leakage: Enter the console to immediately revoke the Key. Approved/rejected approvals can be traced through the audit log.

HMAC Signatures (for Legacy Integrations)

A Webhook with no bound API Key and only a secretKey still uses HMAC-SHA256 shared-secret mode (the X-Webhook-Signature header). Once you bind an API Key to a Webhook, HMAC is no longer accepted — the migration is one-way. For new integrations, use API Key mode directly; for the signature algorithm and migration details, see Trigger a workflow via Webhook.