---
title: "Webhook"
description: "서명된 HTTP 전달을 통해 구현된 사용자, 조직, 멤버십, 초대 및 SAML 인증서 이벤트를 구독합니다."
locale: "ko"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ko/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

## 이벤트 명명 규칙

구현된 이벤트는 `<object>.<action>` 패턴을 따릅니다. vonvon-webhook-event 헤더와 본문 type에는 정확한 이벤트 이름이 포함되며, 모든 전달에는 고유한 `svix-id`도 있습니다.

| 객체 | 작업 |
| --- | --- |
| `user` | 생성됨, 업데이트됨, 삭제됨, 복원됨, 금지됨, 금지 해제됨, 비활성화됨 |
| `organization` | 생성, 업데이트, 삭제, 복원 |
| `organization.auth_policy` | 업데이트됨 |
| `organization.delivery_channels` | 업데이트됨 |
| `organization.social_providers` | 업데이트됨 |
| `organization.outbound_saml_app` | 생성, 삭제됨 |
| `organization.scim_target` | 생성, 삭제됨 |
| `organizationMembership` | 생성, 업데이트, 삭제, 복원 |
| `organizationInvitation` | created, accepted, revoked |
| `connection` | saml\_certificate\_renewed |
| `user.*` | 구현된 모든 사용자 이벤트에 대한 구독 와일드카드입니다. |
| `organization.*` | 점으로 표시된 하위 이벤트를 포함하여 구현된 모든 조직 이벤트에 대한 구독 와일드카드입니다. |
| `organizationMembership.*` | 구현된 모든 조직 멤버십 이벤트에 대한 구독 와일드카드입니다. |
| `*` | 구현된 모든 이벤트에 대한 구독 와일드카드입니다. |

## 페이로드 구조

모든 웹훅 전달은 `Content-Type: application/json`을 사용하는 HTTP POST입니다. 본문에는 정확한 이벤트 `유형`과 해당 `데이터`가 포함됩니다. svix 메타데이터는 요청 헤더에 포함됩니다.

```json
{
  "type": "user.created",
  "data": {
"userId": "user_01abc"
  }
}
```

## 서명 검증

Vonvon는 모든 전송에 HMAC-SHA256 서명을 합니다. 페이로드를 처리하기 전에 서명을 검증하세요. 재사용 공격을 방지하려면 5분이 지난 전송을 거부하세요.

| 헤더 | 설명 |
| --- | --- |
| `svix-id` | 고유 메시지 ID입니다. 재시도 전송 중복 제거에 사용하세요. |
| `svix-timestamp` | 메시지가 전송된 Unix 초 타임스탬프입니다. |
| `svix-signature` | svix-signature 헤더는 리터럴 접두사 v1,로 시작하며, 엔드포인트 서명 시크릿으로 `${svix-id}.${svix-timestamp}.${raw-body}`을 계산한 Base64 인코딩 HMAC-SHA256이 이어집니다. |

```ts
import { verifyWebhook } from '@vonvon-kit/backend'

const result = await verifyWebhook(request, {
  secret: env.VONVON_WEBHOOK_SECRET,
})
if (!result.ok) {
  return new Response('Invalid webhook', { status: 400 })
}
const { type, data } = result.value.payload
```

## 재시도 및 dead-letter

- 전달은 지수 백오프로 재시도되며 최종적으로 dead 상태가 됩니다. 큐 재시도를 모두 소진하면 Instance Manager가 검사하고 재처리할 수 있도록 원본 메시지가 암호화된 데드 레터 레코드로 영구 저장됩니다.
- 전송은 Cloudflare Queues를 통해 인증 경로와 분리되어 있습니다. 느리거나 사용할 수 없는 엔드포인트는 로그인 지연에 영향을 미치지 않습니다.
- 수신 측에서 전송 중복을 제거하려면 `svix-id` 헤더를 사용하세요. 재시도 전송은 원래 시도와 동일한 `svix-id`를 가집니다.

```mermaid
flowchart LR
  Vonvon --> Queue
  Queue -->|HTTPS| Endpoint
  Endpoint -->|2xx| ACK
  Endpoint -->|non-2xx| Retry
  Retry --> Queue
  Retry -->|max_retries| dlq["D1 DLQ"]
```

## 엔드포인트 복구

`POST /v1/webhooks/:id/restore`로 삭제된 엔드포인트를 다시 활성화하고 `POST /v1/webhooks/:id/rotate-secret`로 서명 시크릿을 교체합니다. 새로운 `signing_secret`은 한 번만 반환됩니다. 전달 ID 또는`기간`별 제품 수준 재처리는 구현되지 않았습니다.

```shell
curl -X POST https://vonvon.id/v1/webhooks/webhook_xxx/rotate-secret \
  -H 'Authorization: Bearer sk_live_xxx'
```

## 전달 기록 경계

Vonvon는 pull 방식의 Events API를 제공하지 않습니다. `GET /v1/webhooks`로 구독을 관리하세요. 전달 상태와 큐 데드 레터 재처리는 Instance Manager를 위한 운영 화면이며 테넌트 이벤트 스트림이 아닙니다.

```shell
curl 'https://vonvon.id/v1/webhooks?limit=100' \
  -H 'Authorization: Bearer sk_live_xxx'
```

Source: https://vonvon.id/ko/webhooks/index.mdx