---
title: "webhook"
description: "署名された HTTP 配信を通じて、実装されたユーザー、組織、メンバーシップ、招待、および SAML 証明書イベントをサブスクライブします。"
locale: "ja"
---

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

# webhook

## イベント命名規則

実装されたイベントは、`<object>.<action>` のパターンに従います。 vonvon-webhook-event ヘッダーと本体タイプには正確なイベント名が含まれます。すべての配信には一意の `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.*` | ドット区切りのサブイベントを含む、実装済みの全 Organization イベントを購読するワイルドカード。 |
| `organizationMembership.*` | 実装されたすべての組織メンバーシップ イベントのサブスクリプション ワイルドカード。 |
| `*` | 実装されたすべてのイベントのサブスクリプション ワイルドカード。 |

## ペイロード構造

すべての Webhook 配信は、`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 状態になります。キューの再試行を使い切ると、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 はプル型の 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/ja/webhooks/index.mdx