웹훅 트리거

개요

항목	내용
실행 방식	외부 HTTP 요청
지원 메서드	POST, GET
입력 데이터	요청 본문, 헤더, 쿼리 파라미터

설정 방법

1. 웹훅 URL 생성

워크플로우에 웹훅 트리거를 추가하면 고유한 URL이 생성됩니다.

https://api.suits.work/webhooks/wf_xxxx

2. 외부 시스템에 URL 등록

생성된 URL을 외부 시스템의 웹훅 설정에 등록합니다.

3. 요청 수신 및 워크플로우 실행

외부 시스템에서 요청을 보내면 워크플로우가 실행됩니다.

요청 형식

POST 요청 (권장)

curl -X POST "https://api.suits.work/webhooks/wf_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "payment_completed",
    "orderId": "ORD-12345",
    "amount": 50000,
    "customer": {
      "name": "김철수",
      "email": "[email protected]"
    }
  }'

GET 요청

curl "https://api.suits.work/webhooks/wf_xxxx?event=test&id=123"

출력 데이터

// POST 요청 본문
{{trigger.body}}                    // 전체 JSON
{{trigger.body.event}}              // "payment_completed"
{{trigger.body.orderId}}            // "ORD-12345"
{{trigger.body.customer.name}}      // "김철수"

// 헤더
{{trigger.headers}}                 // 전체 헤더
{{trigger.headers.authorization}}   // Authorization 헤더

// 쿼리 파라미터
{{trigger.query}}                   // 전체 쿼리
{{trigger.query.id}}                // "123"

활용 예시

결제 시스템 연동

외부: 결제 완료 웹훅 전송
       ↓
트리거: 웹훅 수신
액션:
├── 주문 상태 "결제완료"로 변경
├── 고객에게 확인 이메일 발송
└── 재고 차감

외부 폼 연동

외부: 폼 제출 웹훅
       ↓
트리거: 웹훅 수신
액션:
├── 문의 데이터모델에 행 생성
├── 담당자에게 슬랙 알림
└── 자동 응답 이메일 발송

CI/CD 알림

외부: GitHub Actions 완료 웹훅
       ↓
트리거: 웹훅 수신
액션:
├── 배포 로그 기록
└── 팀 채널에 배포 완료 알림

물류 시스템 연동

외부: 송장 생성 웹훅
       ↓
트리거: 웹훅 수신
액션:
├── 주문에 송장번호 업데이트
├── 쇼핑몰 송장 입력 (카페24/네이버)
└── 고객에게 배송 시작 알림

보안

웹훅 URL은 외부에 노출됩니다. 보안을 위해 아래 방법을 사용하세요.

시크릿 토큰 검증

요청 헤더에 시크릿 토큰을 포함하고, 워크플로우에서 검증합니다.

curl -X POST "https://api.suits.work/webhooks/wf_xxxx" \
  -H "X-Webhook-Secret: your-secret-token" \
  -d '{"data": "..."}'

// 조건 필터에서 검증
{{trigger.headers['x-webhook-secret']}} = "your-secret-token"

IP 화이트리스트

알려진 IP에서만 요청을 허용합니다. (Enterprise 플랜)

모범 사례

응답 확인

슈츠 웹훅은 요청을 받으면 즉시 200 응답을 반환합니다. 워크플로우 실행 결과는 별도로 확인하세요.

재시도 처리

외부 시스템이 재시도하는 경우 중복 실행될 수 있습니다. 멱등성을 고려하여 설계하세요.

// orderId로 중복 체크
조건: 동일한 orderId의 주문이 없을 때만 실행

페이로드 검증

예상된 형식의 데이터만 처리하도록 조건을 설정하세요.

조건: {{trigger.body.event}} = "payment_completed"

On this page