> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Webhookの送信先作成API > DiditでWebhookの送信先を新規登録するAPIです。バージョン、購読するイベント、送信先ごとの署名シークレットを指定できます。Webhookをプログラムで管理でき、料金は呼び出しごとの従量課金です。 Webhook送信先作成APIのプロンプト プロンプトをクリップボードにコピー \

\`Register a new webhook destination for my Didit application through the Management API.

Endpoint:
POST https://verification.didit.me/v3/webhook/destinations/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
\- Create a destination where Didit pushes the events I subscribe to. Each destination is an independent (URL, signing secret, payload version, event subscription) tuple.

Request body (application/json):
\{
"label": "Production session webhooks",        // required, human-readable
"url": "https://yourapp.com/webhooks/didit",   // required, HTTPS URL; must be unique among the application's destinations
"enabled": true,                                 // optional, default true
"webhook_version": "v3",                        // optional, "v1" | "v2" | "v3" — v3 is current/recommended
"subscribed_events": ["status.updated", "data.updated"]  // required, at least one supported event
}

Supported subscribed_events values (no wildcard):
\- status.updated, data.updated — KYC/KYB session lifecycle.
\- user.status.updated, user.data.updated — User entity changes.
\- business.status.updated, business.data.updated — Business entity changes.
\- activity.created — accepted and covered by Try Webhook, but not delivered for live traffic today.
\- transaction.created, transaction.status.updated — Transaction monitoring events.
\- travel_rule.status.updated — a Travel Rule exchange changed status.
\- workflow.compliance_changed — a published workflow's compliance status changed.
\- transaction_rule_suggestions.created — a rule suggestion run proposed new rule changes.
\- The full list, including the Investigator and Authentication families, is at /integration/webhooks#event-types.

Critical: capture secret_shared_key from the response and store it securely.
\- The response includes secret_shared_key — this is the HMAC signing secret used to compute X-Signature, X-Signature-V2, and X-Signature-Simple headers on every webhook delivered to this URL. Verify with X-Signature-V2; X-Signature-Simple is deprecated and authenticates the envelope only.
\- Store the secret from the create response. GET /v3/webhook/destinations/{destination_uuid}/ also returns it in full to your API key, but storing it on create avoids leaking it through follow-up reads.
\- The secret is unique per-destination.
\- The rest of the 201 body has the same shape as GET /v3/webhook/destinations/{destination_uuid}/: secret_last4, health_status "healthy", a summary with zero counts and null times, and created_by_email and created_by_name set to null for a destination created with an API key.

Example call:
curl -X POST "https://verification.didit.me/v3/webhook/destinations/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{
"label": "Production session webhooks",
"url": "https://yourapp.com/webhooks/didit",
"webhook_version": "v3",
"subscribed_events": ["status.updated", "data.updated"]
}'

Signature verification quick-start (HMAC-SHA256 over the raw request body):
import hmac, hashlib
def verify(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)

Always verify against the raw request body, not the parsed JSON. See /integration/webhooks for the full v3 signature scheme.

Failure modes:
\- 400: duplicate URL among the application's destinations, empty subscribed_events, unknown event name, or invalid URL.
\- 401 — missing or malformed x-api-key.
\- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.

Side effects:
\- A new destination is created and will start receiving deliveries for subscribed_events immediately (assuming enabled: true).
\- Not idempotent — repeated POSTs with different metadata create separate destinations.

For the full integration shape, see /integration/integration-prompt.`

\
貼り付け先 Webhookの送信先を使うと、Diditのイベントごとに異なるURLへ送信できます。各送信先は、それぞれ独自の`secret_shared_key`、`webhook_version`、`subscribed_events`リストを持ちます。## `subscribed_events`の仕組み`subscribed_events`は、イベント名を正確に指定する必須の配列です。Diditは、ペイロードの`webhook_type`が配列内のいずれかの値と一致する場合にのみ、この送信先へWebhookを配信します。- イベントを少なくとも1つ含めてください。 - 以下に記載されたサポート対象のイベント名のみを使用してください。 - 配信を受けたいイベントをすべて追加してください。`*`や`all`のようなワイルドカード値はありません。 - 製品領域ごとに異なるシステムへ振り分けるには、異なる`subscribed_events`リストを持つ送信先を複数作成してください。## イベントカタログ| イベント | 購読が必要なケース | | - | - | | `status.updated` | ユーザー認証(KYC)または法人確認 (KYB)のセッションのステータスが変わったとき。KYBのペイロードには`session_kind: "business"`と`business_session_id`が含まれます。 | | `data.updated` | 作成後にセッションの検証データが修正または更新されたとき。例として、レビュアーによるKYC、住所証明、KYBデータの編集があります。 | | `user.status.updated` | Userエンティティのステータスが変わったとき。例:`ACTIVE`、`FLAGGED`、`BLOCKED`。 | | `user.data.updated` | Userエンティティのプロフィール、カウンター、メタデータ、書類、または集約された検証フィールドが変わったとき。 | | `business.status.updated` | Businessエンティティのステータスが変わったとき。たとえば、手動レビュー、KYBの結果、ブロックリストのアクションの後です。 | | `business.data.updated` | Businessエンティティのプロフィール、カウンター、メタデータ、登記フィールド、または集約された検証フィールドが変わったとき。 | | `activity.created` | `subscribed_events`では受け付けられ、**Try Webhook**の対象にもなりますが、現在Diditは本番トラフィックではこのイベントを配信していません。 | | `transaction.created` | トランザクションモニタリングの取引が作成され、最初のルール評価が完了したとき。 | | `transaction.status.updated` | ルール、アナリストによるレビュー、是正対応、プロバイダーの更新、またはAPI・コンソールでのアクションの後に取引のステータスが変わったとき。バックグラウンドで再試行された暗号資産スクリーニングが完了したときにも1回送信されます。 | | `travel_rule.status.updated` | [トラベルルール](https://docs.didit.me/ja/transaction-monitoring/travel-rule.md)のやり取りのステータスが変わったとき。 | | `workflow.compliance_changed` | 公開済みワークフローのコンプライアンスステータスが再評価の後に変わったとき。 | | `transaction_rule_suggestions.created` | ルール提案の実行で新しいルール変更が提案されたとき。 |Investigator(`investigator.*`)およびAuthentication(`auth.*`)のイベントファミリーも受け付けられます。すべてのイベントとそのペイロードは[Webhooks](https://docs.didit.me/ja/integration/webhooks.md#イベントタイプ)に記載されています。よく使われる購読の組み合わせ:```json theme={null} { "subscribed_events": ["status.updated", "data.updated"] } ``````json theme={null} { "subscribed_events": ["transaction.created", "transaction.status.updated"] } ``````json theme={null} { "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } ```ペイロードの例と署名のコードについては、[Webhookガイド](https://docs.didit.me/ja/integration/webhooks.md)を参照してください。 ## OpenAPI ````yaml ja/openapi-25.json POST /v3/webhook/destinations/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 本人確認API。x-api-keyヘッダーで認証します。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/destinations/: post: tags: - Webhook summary: Webhookの送信先を作成 description: >- Webhookの送信先を作成します。レスポンスには自動生成されたHMAC署名用シークレット`secret_shared_key`が含まれます（後から`GET /v3/webhook/destinations/{destination_uuid}/`でも取得できます）。`subscribed_events`には必ず1つ以上のイベントを指定して送信してください（ワイルドカードは使用できません）。明示的な空のリストは400で拒否され、フィールドを省略すると何も購読しない送信先が作成され、その送信先はWebhookを一切受信しません。`(application, url)`の組み合わせは、アプリケーションの送信先間で一意である必要があります。 operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Console → Webhooksに表示される、人が読める名前。複数の送信先がある場合に区別しやすくなります（例："Prod"、"Staging mirror"）。 url: type: string format: uri description: >- `POST`リクエストを受信するHTTPS URL。アプリケーションの送信先の中で一意である必要があります。安定した堅牢なエンドポイントを使用してください。Diditは失敗した配信をバックオフスケジュールに従って再試行します。 maxLength: 2000 enabled: type: boolean default: true description: >- `false`の場合、送信先は保存されますが、DiditはこのWebhookの送信先にWebhookを一切送信しません。保留しておきたいステージング用の設定に便利です。 webhook_version: type: string enum: - v1 - v2 - v3 description: >- Diditが送信するペイロードのスキーマバージョン。`v3`が現在の推奨形式です。旧バージョンは従来の連携との後方互換性のために維持されています。 subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- 配信するイベントです。実質的に必須です。明示的な`[]`は400で拒否され、フィールドを省略すると、サブスクリプションがなく何も受信しない送信先が作成されます。 examples: session_updates: summary: セッションのステータスとデータの更新 value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: トランザクションモニタリングの更新 value: label: Transaction monitoring webhooks url: https://yourapp.com/webhooks/didit-transactions webhook_version: v3 subscribed_events: - transaction.created - transaction.status.updated entity_updates: summary: ユーザーおよび企業エンティティの更新 value: label: Entity lifecycle webhooks url: https://yourapp.com/webhooks/didit-entities webhook_version: v3 subscribed_events: - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created responses: '201': description: 送信先が作成されました。`secret_shared_key`はHMAC署名用のシークレットです。今すぐ保存してください。 content: application/json: schema: type: object properties: uuid: type: string format: uuid description: 不変の送信先識別子。以降の呼び出しで`{destination_uuid}`として使用します。 label: type: string url: type: string format: uri enabled: type: boolean webhook_version: type: string enum: - v1 - v2 - v3 secret_shared_key: type: string description: >- この送信先に紐付けられた、自動生成のHMAC署名シークレット（43文字のURLセーフなトークン）。受信したWebhookの署名ヘッダーの検証に使用します。APIキーで呼び出した場合は常に完全な値が返されます。Consoleユーザーには`read:webhooks`権限が必要で、権限がない場合は空文字列が表示されます。 secret_last4: type: string description: >- 送信先の現在の署名シークレットの末尾4文字。シークレットを区別するために使用します。署名の検証にはこれだけでは不十分です。 previous_secret_expires_at: type: string format: date-time nullable: true description: >- Business Consoleで送信先の署名シークレットをローテーションしてから24時間、設定されます。この時刻までは、送信先へのすべての配信に、置き換えられたシークレットで作成された`X-Signature-Previous`、`X-Signature-V2-Previous`、`X-Signature-Simple-Previous`も付与されます（[署名検証](/ja/integration/webhooks#署名検証)を参照）。過去24時間にローテーションが行われていない場合は`null`です。 subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- 送信先を作成したBusiness Consoleメンバーのメールアドレス。APIキーで作成された送信先の場合は`null`。 created_by_name: type: string nullable: true description: >- 送信先を作成したBusiness Consoleメンバーの名前。APIキーで作成された送信先の場合は`null`です。 created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- 配信の健全性。`failing`: 送信先が最後に正常に応答して以降、3件以上の連続したイベントで最初の配信試行が失敗した状態です（`failing_streak`を参照）。`degraded`: failingではないものの、過去24時間以内に配信試行が失敗し、そのイベントがその後の試行でまだ配信されていない状態です。再試行または再送信で配信されると、この状態は解消されます。`healthy`: どちらにも該当しない状態です。`enabled`とは独立しています。失敗した試行とは、HTTP 400以上で応答された試行、またはまったく応答がなかった試行です。 failing_streak: type: integer description: >- 過去30日以内に、送信先が最後に成功応答して以降、最初の配信試行に連続して失敗したイベントの数です。再試行はカウントされず、再試行や再送を含め、いずれかの試行が成功すると連続記録は途切れます。最後の成功以降に失敗したイベントがない場合は`0`です。 failing_since: type: string format: date-time nullable: true description: >- 現在の`failing_streak`における最初の失敗した試行が行われた日時。`failing_streak`が`0`の場合は`null`。 last_success_at: type: string format: date-time nullable: true description: >- 過去30日以内に、送信先が配信に対して400未満のHTTPステータスで最後に応答した日時。その期間内に該当する応答がない場合は`null`。 environment: type: string enum: - live - sandbox description: 送信先を所有するアプリケーションの環境。 summary: type: object description: >- 直近`metrics_window_days`（30）日間の配信メトリクス。`last_delivery_at`は、いつ行われたかにかかわらず最新の試行です。 properties: total_deliveries: type: integer failed_deliveries: type: integer error_rate_percentage: type: integer min_response_time_ms: type: integer nullable: true avg_response_time_ms: type: integer nullable: true max_response_time_ms: type: integer nullable: true last_delivery_at: type: string format: date-time nullable: true metrics_window_days: type: integer description: その他のサマリー指標が対象とする期間の長さ（日数）。常に`30`です。 examples: Created: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true webhook_version: v3 secret_shared_key: tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ secret_last4: 0xnQ previous_secret_expires_at: null subscribed_events: - status.updated - data.updated created_by_email: null created_by_name: null created_at: '2026-05-17T10:00:00Z' updated_at: '2026-05-17T10:00:00Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: null environment: live summary: total_deliveries: 0 failed_deliveries: 0 error_rate_percentage: 0 min_response_time_ms: null avg_response_time_ms: null max_response_time_ms: null last_delivery_at: null metrics_window_days: 30 '400': description: >- バリデーションに失敗しました。通常は、URLの重複、`subscribed_events`の欠落または無効、あるいは不明なイベント名が原因です。 content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events list: value: subscribed_events: - At least one subscribed event is required. Unknown event: value: subscribed_events: - 'Unsupported webhook events: foo.bar' '403': description: >- APIキーがない、形式が不正、期限切れ、または別のアプリケーションにスコープされています。キーがない場合は`403`、誤ったキー、失効したキー、期限切れのキーの場合は`401`を返します。 content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: レート制限を超過しました。間隔を空けてから再試行してください。 content: application/json: examples: Throttled: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": ["status.updated", "data.updated"] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.create( label="Production session webhooks", url="https://yourapp.com/webhooks/didit", webhook_version="v3", subscribed_events=["status.updated", "data.updated"], ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.webhooks.destinations.create({ label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"], }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.WebhookEvent; import me.didit.types.WebhooksDestinationsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder() .label("Production session webhooks") .url("https://yourapp.com/webhooks/didit") .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of("v3")) .subscribedEvents(List.of(WebhookEvent.of("status.updated"), WebhookEvent.of("data.updated"))) .build()); System.out.println(result); - lang: php label: PHP source: |- webhooks->destinations->create([ 'label' => 'Production session webhooks', 'url' => 'https://yourapp.com/webhooks/didit', 'webhook_version' => 'v3', 'subscribed_events' => ['status.updated', 'data.updated'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.create( label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"] ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Webhooks.Destinations.CreateAsync(new WebhooksDestinationsCreateParams { Label = "Production session webhooks", Url = "https://yourapp.com/webhooks/didit", WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion("v3"), SubscribedEvents = new WebhookEvent[] { "status.updated", "data.updated" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookSubscribedEvents: type: array description: >- このWebhookの送信先のイベントフィルターです。Diditは、イベントタイプがこれらの値のいずれかに完全に一致するWebhookのみを配信します。ワイルドカードによるサブスクリプションはありません。送信する場合、リストには有効なイベントを1つ以上含める必要があります(明示的な`[]`は400で拒否されます)。リストが空の送信先(作成時にフィールドを省略した場合)は何も受信しません。更新時、リストはマージされず、常に全体が置き換えられます。 minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated WebhookEvent: type: string description: >- サポートされているWebhookイベント名。`subscribed_events`ではこれらの文字列を正確に使用してください。サポートされていない値は拒否されます。 enum: - status.updated - data.updated - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created - transaction.created - transaction.status.updated - travel_rule.status.updated - workflow.compliance_changed - transaction_rule_suggestions.created - auth.signup - auth.login - auth.login_failed - auth.password_reset_requested - auth.password_reset_completed - auth.mfa_changed - auth.new_device - auth.account_locked - investigator.report.ready - investigator.decision.automated - investigator.decision.overridden - investigator.decision.contested - investigator.question.raised - investigator.automation.paused - investigator.rfi.answered - investigator.rfi.overdue - investigator.drift.detected - investigator.sla.breached - investigator.qa.failed - investigator.external.report.ready securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.