DocumentPlateforme ouverte APIPoint de terminaison du webhook

Point de terminaison du webhook

Déclencheur de workflow + réponse d'approbation (POST + lien GET en un clic).

Le point de terminaison Webhook est utilisé pour les « événements push actifs provenant de systèmes externes ». Deux catégories : déclencheur de flux de travail (le système externe pousse les données → extrait l'exécution du flux de travail) et rappel d'approbation (le système externe pousse la décision → termine l'étape d'approbation manuelle).

1. Déclenchement du workflow

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

Créez d'abord un Webhook dans la console : liez-le au workflow cible et sélectionnez une API Key dotée du scope WEBHOOK_TRIGGER. Ensuite, le système externe envoie une requête POST vers l'URL de déclenchement avec un objet JSON (1 MB au maximum) ; les champs de premier niveau du payload sont mappés vers les variables du workflow selon variableMapping ou la règle de correspondance par nom.

Pour les étapes de création complètes, l'exemple de déclenchement en curl, les règles de mappage des variables, la table des codes d'erreur et le mode de compatibilité HMAC, voir Déclencher un workflow par Webhook ; cette page ne présente que le contrat des endpoints côté plateforme ouverte.

Limites d'autorisation

double vérification

Un apiKeyId est lié au Webhook lors de sa création. Au moment du déclenchement, la Key résolue à partir du Token de la requête doit être exactement celle qui est liée (key id strictement identique), et la Key et le Webhook doivent appartenir au même compte. Cela garantit que même si une Key dotée du scope WEBHOOK_TRIGGER fuite, elle ne peut déclencher que le Webhook auquel elle est explicitement liée, et non le workflow d'autrui. Un Webhook auquel une API Key est liée n'accepte plus les signatures HMAC.

2. Réponse d'approbation (méthode POST)

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

Sert à soumettre des décisions d'approbation depuis un système externe (logique d'automatisation, Slack Bot, traitement des réponses par e-mail, etc.). Le corps de requête est limité à 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"
  }'

Réponse réussie :

json

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

Champs de requête

Champ	Tapez	Description
`approvalId`	string	Obtenir de l'événement de l'étape manual_approval/de la liste d'approbation/du modèle de notification
`decision`	string	"approuver" ou "rejeter" (insensible à la casse)
`comment`	string	Facultatif, enregistré dans l'historique des approbations

Réponses d'erreur

code d'état	sens
`400`	decision n'est ni approve ni reject
`401`	API Key invalide ou dépourvue du scope APPROVAL_RESPOND
`403`	Le propriétaire de la Key n'est pas un approbateur autorisé pour cette approbation
`404`	L'approbation n'existe pas ou n'est pas visible par le propriétaire de la Key
`409`	L'approbation a déjà été traitée ; une nouvelle décision est impossible
`429`	Requêtes trop fréquentes ; la réponse inclut les en-têtes Retry-After et X-RateLimit-*

3. Lien d'approbation en un clic (méthode GET)

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

Afin de permettre à l'approbateur de cliquer sur un lien dans l'e-mail/Slack/Telegram pour terminer l'approbation, un point de terminaison sous la forme de GET est fourni. La réponse est une page HTML, pas 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 première ouverture, le lien n'affiche qu'une page de confirmation ; la décision n'est réellement soumise qu'après avoir cliqué sur le bouton de confirmation de la page (l'URL est complétée par confirm=1). Les robots de prévisualisation de liens des clients de messagerie et des IM ne récupèrent que la page de confirmation et ne peuvent pas approuver par erreur.

Vous pouvez intégrer ce type de lien dans les messages de notification d'approbation, par exemple :

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

Contraintes de sécurité pour les liens en un clic

L'API Key utilisée pour l'approbation en un clic doit avoir une durée de validité courte (24 à 72 heures recommandées)
La portée est strictement limitée à APPROVAL_RESPOND, ne pas mélanger avec d'autres autorisations
Transférer le lien équivaut à remettre le pouvoir d'approbation - ne publiez pas de liens en texte clair dans le groupe, il est préférable de les envoyer par message privé
En cas de fuite de lien : Entrez dans la console pour révoquer immédiatement la clé. Les approbations approuvées/rejetées peuvent être retracées via le journal d’audit.

Signature HMAC (compatibilité avec les anciennes intégrations)

Un Webhook sans API Key liée et configuré uniquement avec secretKey continue d'utiliser le mode de clé partagée HMAC-SHA256 (en-tête X-Webhook-Signature). Dès qu'une API Key est liée au Webhook, HMAC n'est plus accepté ; la migration est à sens unique. Pour les nouvelles intégrations, utilisez directement le mode API Key ; pour l'algorithme de signature et les détails de migration, voir Déclencher un workflow par Webhook.