웹훅 트리거 설정

웹훅 트리거는 고유한 URL로 데이터를 보내 외부 서비스가 워크플로우를 시작할 수 있게 합니다. 양식, 서드파티 앱 및 커스텀 통합과 연결하는 데 사용하세요.

웹훅을 언제 사용할지

사용 사례	예시
웹 폼	문의 폼 제출 시 리드가 생성됩니다
서드파티 앱	Stripe 결제 → 고객 레코드 생성
커스텀 통합	사용자 앱 → Twenty 자동화
노코드 도구	Zapier, Make, n8n 연결

단계별 설정

1단계: 워크플로우 생성

설정 → 워크플로우로 이동
+ 새 워크플로우를 클릭
이름을 지정합니다(예: “웹사이트 폼 제출”)

2단계: 웹훅 트리거 구성

트리거 블록을 클릭하세요
웹훅을 선택
다음과 같은 고유한 웹훅 URL이 제공됩니다:
https://api.twenty.com/webhooks/workflow/abc123...
이 URL을 복사하세요—외부 서비스에 필요합니다

3단계: 예상 데이터 구조 정의

POST 요청의 경우, 예상 본문 구조를 정의하세요:

예상 본문 정의를 클릭
서비스가 보내는 형식과 일치하는 샘플 JSON을 입력하세요:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "company": "Acme Inc",
  "message": "Interested in your product"
}

저장을 클릭하세요—이렇게 하면 이후 단계에서 사용할 수 있는 변수가 생성됩니다

4단계: 액션 추가

이제 웹훅 데이터를 사용하는 액션을 추가하세요: 예시: 사람 레코드 생성

레코드 생성 액션을 추가
People 객체를 선택
필드 매핑:

필드	값
이름	`{{trigger.body.firstName}}`
성	`{{trigger.body.lastName}}`
이메일	`{{trigger.body.email}}`
회사	`{{trigger.body.company}}` 기준으로 검색 또는 생성

5단계: 웹훅 테스트

활성화하기 전에 웹훅을 테스트하세요: cURL 사용:

curl -X POST https://api.twenty.com/webhooks/workflow/abc123... \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Test","lastName":"User","email":"test@example.com"}'

Postman 등 사용:

웹훅 URL로 POST 요청을 생성
Content-Type 헤더를 application/json으로 설정
테스트 JSON 본문을 추가
전송하고 워크플로우 실행을 확인하세요.

6단계: 활성화

테스트가 완료되면 활성화를 클릭하여 워크플로우를 라이브로 전환하세요.

다양한 데이터 구조 처리

중첩 데이터

웹훅이 중첩 데이터를 보내는 경우:

{
  "contact": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "source": "website"
}

다음과 같이 참조: {{trigger.body.contact.email}}

배열

데이터에 배열이 포함된 경우:

{
  "items": [
    {"name": "Product A", "qty": 2},
    {"name": "Product B", "qty": 1}
  ]
}

배열 처리 방식은 사용 사례에 따라 다릅니다: 항목 개수를 알 수 없음 → Iterator 사용 배열의 각 항목을 처리해야 하는 경우(예: 각 항목마다 레코드 생성), 배열을 파싱하기 위해 Code 액션을 추가한 다음 Iterator를 사용하세요:

export const main = async (params: { items: any }) => {
  const items = typeof params.items === "string"
    ? JSON.parse(params.items)
    : params.items;
  return { items };
};

그런 다음 Iterator로 순회합니다: {{code.items}} 알려진/특정 필드 → 명명된 필드로 추출 배열에 개별적으로 접근하려는 특정 필드가 포함되어 있다면(예: 위치 0은 항상 “first name”, 위치 1은 항상 “last name”인 폼 답변), 이를 추출하기 위해 Code 액션을 추가하세요:

export const main = async (params: { items: any }) => {
  const items = typeof params.items === "string"
    ? JSON.parse(params.items)
    : params.items;

  return {
    product: {
      name: items[0]?.name || "",
      qty: items[0]?.qty || 0
    }
  };
};

이제 이후 단계에서 product.name 및 product.qty를 개별적으로 선택할 수 있습니다.

배열 처리에 대한 자세한 내용은 Code 액션에서 배열 처리하기를 참조하세요.

개요

데이터 모델

데이터 마이그레이션

캘린더 및 이메일

워크플로우

AI

레이아웃

대시보드

권한 및 접근

청구

설정

법무

웹훅을 언제 사용할지

단계별 설정

1단계: 워크플로우 생성

2단계: 웹훅 트리거 구성

3단계: 예상 데이터 구조 정의

4단계: 액션 추가

5단계: 웹훅 테스트

6단계: 활성화

다양한 데이터 구조 처리

중첩 데이터

배열

관련 항목

​웹훅을 언제 사용할지

​단계별 설정

​1단계: 워크플로우 생성

​2단계: 웹훅 트리거 구성

​3단계: 예상 데이터 구조 정의

​4단계: 액션 추가

​5단계: 웹훅 테스트

​6단계: 활성화

​다양한 데이터 구조 처리

​중첩 데이터

​배열

​관련 항목

웹훅을 언제 사용할지

단계별 설정

1단계: 워크플로우 생성

2단계: 웹훅 트리거 구성

3단계: 예상 데이터 구조 정의

4단계: 액션 추가

5단계: 웹훅 테스트

6단계: 활성화

다양한 데이터 구조 처리

중첩 데이터

배열

관련 항목