> For the complete documentation index, see [llms.txt](https://api-docs.roundhr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.roundhr.com/round-api/api-reference/webhooks/create.md).

# 웹훅 등록

## Webhook 등록

<mark style="color:yellow;">`POST`</mark> `https://api.roundhr.com/v1/webhooks`

새로운 Webhook을 등록합니다.

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Name          | Type      | 필수         | Description        |
| ------------- | --------- | ---------- | ------------------ |
| callback\_url | string    | `required` | 이벤트 발생 시 호출할 URL   |
| signing\_key  | string    | `optional` | 서명 검증을 위한 비밀 키     |
| active        | boolean   | `optional` | 활성화 여부 (기본값: true) |
| kinds         | string\[] | `optional` | 구독할 이벤트 타입 배열      |

**구독 가능한 이벤트 (kinds)**

| 이벤트 타입                    | 설명                |
| ------------------------- | ----------------- |
| candidate\_stage\_changed | 지원자의 채용 단계가 변경될 때 |
| candidate\_pass           | 지원자가 합격 단계로 이동할 때 |
| feedback\_created         | 평가가 생성될 때         |
| feedback\_completed       | 평가가 완료될 때         |
| interview\_scheduled      | 면접 일정이 확정될 때      |

{% hint style="info" %}
각 이벤트의 상세 payload는 [Webhook 이벤트 목록](/round-webhook/events.md)을 참조하세요.
{% endhint %}

**요청 예제**

```bash
curl -X POST https://api.roundhr.com/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "callback_url": "https://example.com/webhook",
    "signing_key": "your_secret_key",
    "kinds": ["candidate_stage_changed", "feedback_created"]
  }'
```

**응답 예제**

{% tabs %}
{% tab title="200" %}

```json
{
  "resource": {
    "code": "WH12345678",
    "active": true,
    "provider": "round",
    "callback_url": "https://example.com/webhook",
    "signing_key": "your_secret_key",
    "events": [
      "candidate_stage_changed",
      "feedback_created"
    ],
    "created_at": "2025-01-15T00:00:00+09:00",
    "updated_at": "2025-01-15T00:00:00+09:00"
  }
}
```

{% endtab %}
{% endtabs %}