---
title: 웹훅
icon: satellite-dish
description: 레코드가 변경될 때 알림을 받으세요 — 생성, 업데이트, 삭제마다 귀하의 엔드포인트로 HTTP POST를 전송합니다.
---

import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

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

## 웹훅 생성

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

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

<VimeoEmbed videoId="928786708" title="웹훅 생성" />

### 웹훅 관리

**편집**: 웹훅을 클릭 → URL 업데이트 → **저장**

**삭제**: 웹훅을 클릭 → **삭제** → 확인

## 이벤트

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

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

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

## 페이로드 형식

각 웹훅은 JSON 본문을 포함한 HTTP 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"
}
```

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

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

## 웹훅 검증

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

### 헤더

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

### 검증 단계

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

### 예시(Node.js)

```javascript
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로 데이터를 수신합니다        |

외부 데이터를 수신하려면 [웹훅 트리거 설정](/l/ko/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger)을 참조하세요.