웹훅 - Twenty Documentation

레코드가 생성, 업데이트 또는 삭제될 때마다 Twenty가 귀하의 URL로 HTTP POST를 전송합니다. 사용자 지정 오브젝트를 포함한 모든 오브젝트 유형이 지원됩니다.

웹훅 생성

설정 → API 및 웹훅 → 웹훅으로 이동
+ 웹훅 생성 클릭
웹훅 URL을 입력하세요(공개적으로 액세스 가능해야 함)
저장을 클릭합니다

웹훅이 즉시 활성화되어 알림 전송을 시작합니다.

웹훅 관리

편집: 웹훅을 클릭 → URL 업데이트 → 저장 삭제: 웹훅을 클릭 → 삭제 → 확인

이벤트

Twenty는 다음 이벤트 유형에 대해 웹훅을 전송합니다:

이벤트	예시
레코드 생성됨	`person.created`, `company.created`, `note.created`
레코드 업데이트됨	`person.updated`, `company.updated`, `opportunity.updated`
레코드 삭제됨	`person.deleted`, `company.deleted`

모든 이벤트 유형은 귀하의 웹훅 URL로 전송됩니다. 이벤트 필터링은 향후 릴리스에서 추가될 수 있습니다.

페이로드 형식

각 웹훅은 JSON 본문을 포함한 HTTP POST를 전송합니다:

{
  "event": "person.created",
  "data": {
    "id": "abc12345",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "alice@example.com",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}

필드	설명
`event`	무슨 일이 발생했는지(예: `person.created`)
`data`	생성/업데이트/삭제된 전체 레코드
`timestamp`	이벤트가 발생한 시각(UTC)

수신을 확인하기 위해 2xx HTTP 상태(200-299)로 응답하세요. 2xx가 아닌 응답은 전달 실패로 기록됩니다.

웹훅 검증

Twenty는 보안을 위해 각 웹훅 요청에 서명합니다. 요청의 진위를 보장하기 위해 서명을 검증하세요.

헤더

헤더	설명
`X-Twenty-Webhook-Signature`	HMAC SHA256 서명
`X-Twenty-Webhook-Timestamp`	요청 타임스탬프

검증 단계

X-Twenty-Webhook-Timestamp에서 타임스탬프를 가져옵니다
다음 문자열을 생성합니다: {timestamp}:{JSON payload}
웹훅 비밀을 사용하여 HMAC SHA256을 계산합니다
X-Twenty-Webhook-Signature와 비교합니다

예시(Node.js)

const crypto = require("crypto");

const timestamp = req.headers["x-twenty-webhook-timestamp"];
const payload = JSON.stringify(req.body);
const secret = "your-webhook-secret";

const stringToSign = `${timestamp}:${payload}`;
const expectedSignature = crypto
  .createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");

const receivedSignature = req.headers["x-twenty-webhook-signature"];
const isValid = crypto.timingSafeEqual(
  Buffer.from(expectedSignature, "hex"),
  Buffer.from(receivedSignature, "hex")
);

웹훅 vs 워크플로

방법	방향	사용 사례
웹훅	OUT	레코드 변경 사항을 외부 시스템에 자동으로 알립니다
워크플로 + HTTP 요청	OUT	사용자 지정 로직(필터, 변환)으로 데이터를 외부로 전송합니다
워크플로 웹훅 트리거	IN	외부 시스템에서 Twenty로 데이터를 수신합니다

외부 데이터를 수신하려면 웹훅 트리거 설정을 참조하세요.

개요

앱

API

셀프 호스팅

기여

웹훅

웹훅 생성

웹훅 관리

이벤트

페이로드 형식

웹훅 검증

헤더

검증 단계

예시(Node.js)

웹훅 vs 워크플로

​웹훅 생성

​웹훅 관리

​이벤트

​페이로드 형식

​웹훅 검증

​헤더

​검증 단계

​예시(Node.js)

​웹훅 vs 워크플로

웹훅 생성

웹훅 관리

이벤트

페이로드 형식

웹훅 검증

헤더

검증 단계

예시(Node.js)

웹훅 vs 워크플로