DocumentoPlataforma abierta APIPunto final del webhook

Punto final del webhook

Activador de flujo de trabajo + respuesta de aprobación (POST + OBTENER enlace de un clic).

El punto final de Webhook se utiliza para "eventos push activos desde sistemas externos". Dos categorías: activador del flujo de trabajo (el sistema externo envía datos → inicia la ejecución del flujo de trabajo) y devolución de llamada de aprobación (el sistema externo envía la decisión → completa el paso manual_approval).

1. Activación del flujo de trabajo

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

Primero cree un Webhook en la consola: enlácelo al workflow de destino y elija una API Key con el scope WEBHOOK_TRIGGER. Después, el sistema externo hace POST de un objeto JSON (máximo 1 MB) a la URL de disparo; los campos de nivel superior del payload se mapean a variables del workflow según variableMapping o la regla de nombres coincidentes.

Para los pasos de creación completos, el ejemplo de disparo con curl, las reglas de mapeo de variables, la tabla de códigos de error y el modo compatible con HMAC, consulte Disparar workflows con Webhook; esta página solo lista el contrato de endpoints del lado de la plataforma abierta.

Límites de permiso

doble verificación

Al crear el Webhook se enlaza un apiKeyId. Al dispararlo, la Key resuelta del Token de la solicitud debe ser exactamente la enlazada (el key id debe coincidir por completo), y la Key y el Webhook deben pertenecer a la misma cuenta. Esto garantiza que, aunque se filtre una Key con el scope WEBHOOK_TRIGGER, solo pueda disparar el Webhook al que esté enlazada explícitamente, y no los workflows de otros. Un Webhook ya enlazado a una API Key deja de aceptar firmas HMAC.

2. Respuesta de aprobación (método POST)

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

Se utiliza para enviar decisiones de aprobación desde sistemas externos (lógica de automatización, bots de Slack, procesamiento de respuestas por correo, etc.). El cuerpo de la solicitud tiene un límite de 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"
  }'

Respuesta exitosa:

json

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

Campos de solicitud

campo	Tipo	Descripción
`approvalId`	string	Obtener del evento del paso manual_approval/lista de aprobación/plantilla de notificación
`decision`	string	"aprobar" o "rechazar" (no distingue entre mayúsculas y minúsculas)
`comment`	string	Opcional, registrado en el historial de aprobación.

Respuestas de error

código de estado	significado
`400`	decision no es approve / reject
`401`	API Key inválida o sin el scope APPROVAL_RESPOND
`403`	El propietario de la Key no es el aprobador autorizado de esa aprobación
`404`	La aprobación no existe o no es visible para el propietario de la Key
`409`	La aprobación ya se ha tramitado; no se puede volver a decidir
`429`	Solicitudes demasiado frecuentes; la respuesta incluye los headers Retry-After y X-RateLimit-*

3. Enlace de aprobación con un solo clic (método GET)

GET /api/webhook-trigger/approval/{approvalId}/{decision}?api_key=…
Autenticación: API Key (parámetro de query) · Scope: APPROVAL_RESPOND

Para permitir que el aprobador haga clic en un enlace en el correo electrónico/Slack/Telegram para completar la aprobación, se proporciona un punto final en forma de GET. La respuesta es una página HTML, no 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

La primera vez que se abre el enlace solo se muestra una página de confirmación; solo cuando se pulsa el botón de confirmación de la página (se añade confirm=1 a la URL) se envía realmente la decisión. Los bots de vista previa de enlaces de los clientes de correo y de mensajería instantánea solo capturan la página de confirmación y no aprueban por error.

Puede incrustar este tipo de enlace en el mensaje de notificación de aprobación, por ejemplo:

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

Restricciones de seguridad para enlaces de un clic

La API Key destinada a la aprobación con un clic debería tener una validez corta (se recomiendan 24-72 horas)
El alcance está estrictamente limitado a APPROVAL_RESPOND, no lo mezcle con otros permisos
Reenviar el enlace equivale a entregar la autoridad de aprobación; no publique enlaces de texto claro en el grupo, es mejor enviarlos por mensaje privado.
En caso de pérdida de enlace: Ingrese a la consola para revocar inmediatamente la Clave. Las aprobaciones aprobadas/rechazadas se pueden rastrear a través del registro de auditoría.

Firma HMAC (compatibilidad con integraciones antiguas)

Un Webhook que no esté enlazado a una API Key y solo tenga configurada una secretKey sigue funcionando en modo de clave compartida HMAC-SHA256 (header X-Webhook-Signature). En cuanto se enlaza una API Key al Webhook, HMAC deja de aceptarse; la migración es de un solo sentido. Para nuevas integraciones, use directamente el modo API Key; el algoritmo de firma y los detalles de migración están en Disparar workflows con Webhook.