메인 콘텐츠로 건너뛰기
Header

​
개요

Twenty의 Webhook은 CRM에서 특정 이벤트가 발생할 때 실시간 알림으로 귀하의 애플리케이션에 데이터를 전송하여 API를 보완합니다. API의 변경 사항을 계속해서 폴링하는 대신, 특정 이벤트가 발생할 때 Twenty가 귀하의 시스템으로 데이터를 푸시하도록 웹훅을 설정할 수 있습니다 (예: 새 레코드가 생성되거나 기존 레코드가 업데이트될 때). 이것은 외부 시스템을 Twenty와 즉시 그리고 효율적으로 동기화하는 데 도움이 됩니다. 웹훅을 통해 Twenty는 귀하가 지정한 URL로 이벤트에 대한 세부 정보를 포함한 HTTP POST 요청을 보냅니다. 그런 후 귀하의 애플리케이션에서 해당 데이터를 처리할 수 있습니다(예: 외부 데이터베이스 업데이트, 워크플로우 트리거, 경고 전송 등).

​
웹훅 설정하기

Twenty에서 웹훅을 생성하려면 귀하의 Twenty 앱의 API 및 웹훅 설정을 사용하세요.
  1. 설정으로 이동: 귀하의 Twenty 애플리케이션에서 설정 → API 및 웹훅으로 이동하세요.
  2. 웹훅 생성: 웹훅 아래에서 + 웹훅 생성을 클릭하세요.
  3. URL 입력: Twenty가 웹훅 요청을 보내고자 하는 귀하 서버의 엔드포인트 URL을 제공합니다. 이는 POST 요청을 처리할 수 있는 공개적으로 접근 가능한 URL이어야 합니다.
  4. 저장: 웹훅을 생성하려면 저장을 클릭하세요. 새로운 웹훅은 즉시 활성화됩니다.
다양한 이벤트를 다른 엔드포인트로 전송해야 하는 경우 여러 웹훅을 생성할 수 있습니다. 각 웹훅은 모든 관련 이벤트에 대한 구독입니다 (현재는 Twenty가 주어진 URL로 모든 이벤트 유형을 보냅니다. UI에서 특정 이벤트 유형 필터링이 가능할 수 있습니다). 웹훅을 제거해야 할 경우, 동일한 설정 페이지에서 삭제할 수 있습니다 (웹훅을 선택하고 삭제를 선택하세요).

​
이벤트 및 페이로드

웹훅이 설정되면, CRM 데이터에서 트리거 이벤트가 발생할 때마다 Twenty가 지정된 URL로 HTTP POST 요청을 보냅니다. 웹훅을 트리거하는 일반적인 이벤트는 다음과 같습니다:
  • 레코드 생성됨: 예를 들어, 새로운 사람이 추가됨 (person.created), 새로운 회사가 생성됨 (company.created), 노트가 생성됨 (note.created) 등.
  • 레코드 업데이트됨: 예를 들어, 기존 사람의 정보가 업데이트됨 (person.updated), 회사 레코드가 편집됨 (company.updated) 등.
  • 레코드 삭제됨: 예를 들어, 사람이나 회사가 삭제됨 (person.deleted, company.deleted).
  • 기타 이벤트: 해당되는 경우 다른 개체 이벤트나 사용자 정의 트리거 (예를 들어, 작업이 업데이트되거나 다른 개체가 업데이트된 경우에도 유사한 이벤트 유형이 사용됩니다, task.created, note.updated 등).
웹훅 POST 요청은 본문에 JSON 페이로드를 포함합니다. 페이로드에는 일반적으로 두 가지 사항이 포함됩니다: 이벤트 유형과 그 이벤트와 관련된 데이터 (주로 생성/업데이트된 레코드). 예를 들어, 새로 생성된 사람에 대한 웹훅은 다음과 같은 페이로드를 전송할 수 있습니다: 
{
  "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"
}
이 예시에서는:
  • "이벤트"는 발생한 일을 지정합니다 (person.created).
  • "데이터"는 새 레코드의 세부 정보를 포함하고 있습니다 (API를 통해 그 사람을 요청했을 경우 받게 되는 동일한 정보).
  • "타임스탬프"는 이벤트가 발생한 시간입니다 (UTC 기준).
귀하의 엔드포인트는 POST를 통해 JSON 데이터를 수신할 준비가 되어 있어야 합니다. 일반적으로 JSON을 구문 분석하고, "이벤트" 유형을 확인하여 어떤 일이 발생했는지 이해한 후, "데이터"를 적절히 사용합니다 (예: 시스템에 새 연락처를 생성하거나 기존 연락처를 업데이트). 참고: 웹훅 엔드포인트로부터 2xx HTTP 상태로 응답하여 성공적인 수신을 확인하는 것이 중요합니다. Twenty 웹훅 발신자가 2xx 응답을 받지 못하면, 전송이 실패했다고 간주할 수 있습니다. (추후, 실패한 웹훅을 다시 보내는 재시도 로직이 시도될 수 있으니 데이터를 처리한 후 가능한 빨리 200 OK를 반환하도록 노력하세요).

​
웹훅 검증

웹훅 엔드포인트의 보안을 보장하기 위해, Twenty는 X-Twenty-Webhook-Signature 헤더에 서명을 포함합니다. 이 서명은 귀하의 웹훅 비밀을 사용하여 계산된 요청 페이로드에 대한 HMAC SHA256 해시입니다. 서명을 검증하려면 다음이 필요합니다:
  1. 타임스탬프 (X-Twenty-Webhook-Timestamp 헤더에서)와 콜론, 그리고 페이로드의 JSON 문자열을 연결합니다.
  2. 귀하의 웹훅 비밀을 키로 사용하여 HMAC SHA256 해시를 계산합니다
  3. 결과적인 16진수 다이제스트와 서명 헤더를 비교합니다
다음은 Node.js의 예입니다: 
const crypto = require("crypto");
const timestamp = "1735066639761";
const payload = JSON.stringify({...});
const secret = "your-secret";
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
const signature = crypto.createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");