Webhook 트리거

Webhook은 외부 시스템(GitHub、CI/CD、Lark、IoT、상류 API)이 HTTP POST로 워크플로 실행을 직접 개시하게 합니다. 권장 방식: Webhook에 WEBHOOK_TRIGGER 권한 범위를 가진 API Key 하나를 바인딩하고, 트리거 요청은 이 Key로 인증합니다.

Webhook 생성 및 API Key 바인딩

1. 콘솔 → 계정 설정 → API 키에서 Key 하나를 새로 만들고, scope에서 WEBHOOK_TRIGGER 를 선택(자세한 내용은API Key와 권한 범위）
2. Webhook 목록 또는 워크플로 상세 페이지에서 Webhook을 새로 만들고, 대상 워크플로를 선택하여 이 Key를 바인딩합니다. 생성자는 워크플로에 대한 편집 권한이 필요하며, 바인딩하는 Key는 반드시 자신 명의여야 합니다

관리 API(콘솔 로그인 상태)로도 할 수 있습니다:

curl -X POST https://braidrun.com/api/webhooks \
  -H "Authorization: Bearer <console-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "<workflow-id>",
    "name": "GitHub Push Webhook",
    "apiKeyId": "<api-key-id>",
    "variableMapping": {
      "branch": "ref",
      "repo_name": "repo"
    }
  }'

응답에는 고유한 webhook-id가 포함되며, 트리거 URL은 다음과 같습니다:

POST https://braidrun.com/api/webhooks/<webhook-id>/trigger

Webhook 개수는 요금제에 따라 다릅니다: Pro 3개, Team 10개.

워크플로 트리거

curl -X POST https://braidrun.com/api/webhooks/<webhook-id>/trigger \
  -H "Authorization: Bearer dyk_<id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "ref": "refs/heads/main",
    "repo": "my-app"
  }'

자격 증명은 세 가지 방식으로 전달할 수 있으며, 서버는 다음 순서로 인식합니다:

Authorization: Bearer dyk_<id>_<secret>      # 推荐
X-API-Key: dyk_<id>_<secret>                  # 无法自定义 Authorization 头时
POST .../trigger?api_key=dyk_<id>_<secret>    # 仅限无法设置 header 的场景

성공적인 트리거 반환:

{
  "executionId": "exec_a3b9c8...",
  "webhookId": "<webhook-id>",
  "workflowId": "<workflow-id>",
  "status": "PENDING",
  "startedAt": 1735632891234
}

변수 매핑

variableMapping을 설정하지 않으면 payload 최상위의 문자열 / 숫자 / 불리언 필드가 같은 이름으로 워크플로 변수에 자동 매핑됩니다. 중첩 객체와 배열은 자동 매핑 대상이 아닙니다.

이름을 변경해야 할 때 설정합니다 variableMapping : 키는 워크플로 변수 이름이고 값은 payload 최상위 필드 이름입니다. 최상위 필드만 지원하며 중첩 경로 값은 지원하지 않습니다.

# Webhook 配置
"variableMapping": { "branch": "ref", "repo_name": "repo" }

# 触发 payload
{ "ref": "refs/heads/main", "repo": "my-app" }

# 工作流实际拿到的输入
{ "branch": "refs/heads/main", "repo_name": "my-app" }

payload에 매핑 대상 필드가 없으면 해당 변수는 주입되지 않으며, 워크플로 템플릿의 기본값이 그대로 적용됩니다(빈 문자열로 덮어쓰지 않습니다).

HMAC 서명(기존 연동 호환)

API Key를 바인딩하지 않았지만 secretKey 을(를) 설정한 Webhook은 구버전 HMAC 모드를 사용합니다. 트리거 요청은 header에 서명을 포함해야 합니다:

X-Webhook-Signature: sha256=<hex(HMAC-SHA256(rawRequestBody, secretKey))>

서명 = HmacSHA256(rawRequestBody, secretKey) , hex 문자열을 출력하며 sha256= 접두사는 붙여도 되고 생략해도 됩니다. 비교에 실패하면 401을 반환합니다.

API Key를 바인딩한 Webhook은 더 이상 HMAC 서명을 받지 않으며(secretKey 필드에 값이 남아 있어도 마찬가지입니다), API Key로의 마이그레이션은 단방향입니다. 두 인증 방식을 모두 설정하지 않은 Webhook은 트리거 시 신원을 검증하지 않으므로 URL 자체가 자격 증명과 같으며, 디버깅 단계에서만 이렇게 사용하는 것을 권장합니다.

구버전 트리거 경로 POST /api/webhook-trigger/{webhookId} 은(는) 그대로 유지되며 동작도 동일합니다. 새 연동에는 위의 표준 경로를 사용하세요.

오류 응답

일반적인 액세스 시나리오

• GitHub push — 브랜치 이름과 커밋 작성자를 변수에 매핑하고, workflow가 자동으로 build / test / deploy를 수행합니다
• CI 系统 — 빌드 완료 → 웹훅이 후속 릴리스 파이프라인을 트리거합니다.
• Lark / 飞书机器人 — 특정 명령을 받은 후 작업 일괄 처리 트리거
• IoT 上报 — 장치 알람 → 웹후크가 문제 해결 워크플로를 트리거하고 알람을 수렴합니다.

관리 엔드포인트

목록 GET /api/webhooks, 업데이트 PUT /api/webhooks/{id}, 삭제 DELETE /api/webhooks/{id}, 그리고 GET /api/webhooks/{id}/stats 가 트리거 통계를 반환합니다. 이들은 모두 콘솔 로그인 상태에서 사용하는 인터페이스입니다.

서비스가 다시 시작되면

Webhook으로 트리거된 execution이 서비스 재시작으로 중단되면 자동으로 이어서 실행되지 않습니다. payload는 at-most-once로 처리되며 플랫폼은 재전송을 하지 않습니다. manual_approval에서 승인을 기다리며 멈춰 있는 실행은 예외로, 승인되면 정상적으로 계속 진행됩니다. 재실행이 필요하면 상위 시스템에서 트리거 요청을 다시 한 번 보내면 됩니다(새 execution이 생성됩니다).

관련 페이지

• 오픈 플랫폼 Webhook 엔드포인트(승인 콜백)
• API Key와 권한 범위