8cadd00d34
Created by Github action --------- Co-authored-by: Crowdin Bot <support+bot@crowdin.com> Co-authored-by: github-actions <github-actions@twenty.com>
87 lines
5.9 KiB
Plaintext
87 lines
5.9 KiB
Plaintext
---
|
|
title: Webhooks
|
|
image: /images/docs/getting-started/webhooks.png
|
|
info: 우리의 Webhook 사용 방법 알아보기.
|
|
---
|
|
|
|
<Frame>
|
|
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
|
</Frame>
|
|
|
|
## 개요
|
|
|
|
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의 예입니다:
|
|
|
|
```javascript
|
|
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");
|
|
``` |