주요 콘텐츠로 건너뛰기
문서API 오픈 플랫폼웹훅 엔드포인트

웹훅 엔드포인트

워크플로 트리거 + 승인 응답(POST + 원클릭 링크 GET)

웹훅 엔드포인트는 "외부 시스템의 활성 푸시 이벤트"에 사용됩니다. 두 가지 범주: 워크플로 트리거(외부 시스템에서 데이터 푸시 → 워크플로 실행 실행) 및 승인 콜백(외부 시스템에서 결정 푸시 → 수동 승인 단계 완료).

1. 워크플로 트리거링

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

먼저 콘솔에서 Webhook을 생성합니다: 대상 워크플로에 바인딩하고 WEBHOOK_TRIGGER 범위를 가진 API Key 하나를 선택합니다. 이후 외부 시스템이 트리거 URL로 JSON 객체 하나를 POST하면(최대 1 MB), payload의 최상위 필드가 variableMapping 또는 동명 규칙에 따라 워크플로 변수로 매핑됩니다.

전체 생성 단계, 트리거 curl 예시, 변수 매핑 규칙, 오류 코드 표, HMAC 호환 모드는 Webhook으로 워크플로 트리거 참고. 본 페이지는 오픈 플랫폼 측 엔드포인트 계약만 나열합니다.

권한 경계

다시 확인

Webhook 생성 시 apiKeyId 하나가 바인딩됩니다. 트리거할 때 요청 Token에서 파싱된 Key는 반드시 바인딩된 그 Key여야 하며(key id 완전 일치), Key와 Webhook은 동일한 계정에 속해야 합니다. 이로써 WEBHOOK_TRIGGER 범위를 가진 Key가 유출되더라도 명시적으로 바인딩된 Webhook만 트리거할 수 있고 다른 사람의 워크플로는 트리거할 수 없음이 보장됩니다. API Key가 바인딩된 Webhook은 더 이상 HMAC 서명을 받지 않습니다.

2. 승인 응답(POST 방식)

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

외부 시스템(자동화 로직, Slack Bot, 이메일 회신 처리 등)에서 승인 결정을 제출하는 데 사용합니다. 요청 본문 상한은 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"
  }'

성공적인 응답:

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

요청 필드

필드유형설명
approvalIdstringmanual_approval 단계 이벤트/승인 목록/알림 템플릿에서 가져오기
decisionstring"승인" 또는 "거부"(대소문자 구분 안 함)
commentstring선택사항, 승인내역에 기록됨

오류 응답

상태 코드의미
400decision이 approve / reject가 아닙니다
401API Key가 유효하지 않거나 APPROVAL_RESPOND 범위가 없습니다
403Key 소유자가 해당 승인의 권한 있는 승인자가 아닙니다
404승인이 존재하지 않거나 Key 소유자에게 보이지 않습니다
409승인이 이미 처리되어 중복 결정을 할 수 없습니다
429요청이 너무 잦으며, 응답에 Retry-After와 X-RateLimit-* 헤더가 포함됩니다

3. 원클릭 링크 승인(GET 방식)

GET /api/webhook-trigger/approval/{approvalId}/{decision}?api_key=…
인증: API Key(query 파라미터)· Scope: APPROVAL_RESPOND

승인자가 이메일/Slack/텔레그램의 링크를 클릭하여 승인을 완료할 수 있도록 GET 형태의 엔드포인트를 제공합니다. 응답은 JSON이 아닌 HTML 페이지입니다.

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

링크를 처음 열면 확인 페이지만 표시되며, 페이지의 확인 버튼을 클릭해야(URL에 confirm=1 추가) 비로소 결정이 실제로 제출됩니다. 이메일 클라이언트와 IM의 링크 미리보기 봇은 확인 페이지만 가져오므로 잘못 승인하지 않습니다.

이런 링크를 승인 알림 메시지에 삽입할 수 있습니다. 예:

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>)
원클릭 링크에 대한 보안 제약
  • 원클릭 승인에 사용하는 API Key는 짧은 유효기간을 설정해야 합니다(24~72시간 권장)
  • 범위는 APPROVAL_RESPOND로 엄격하게 제한되며 다른 권한과 혼합하지 마세요.
  • 링크 전달은 승인 권한을 넘겨주는 것과 같습니다. 그룹에 일반 텍스트 링크를 게시하지 말고 개인 메시지를 통해 보내는 것이 가장 좋습니다.
  • 링크가 유출된 경우: 콘솔에 들어가 즉시 키를 취소하세요. 승인/거부 승인은 감사 로그를 통해 추적할 수 있습니다.

HMAC 서명(기존 연동 호환)

API Key가 바인딩되지 않고 secretKey만 설정된 Webhook은 여전히 HMAC-SHA256 공유 비밀 키 모드로 동작합니다(요청 헤더 X-Webhook-Signature). Webhook에 API Key를 바인딩하면 HMAC은 더 이상 허용되지 않으며, 마이그레이션은 단방향입니다. 새 연동은 바로 API Key 모드를 사용하십시오. 서명 알고리즘과 마이그레이션 세부는 Webhook으로 워크플로 트리거.