> ## 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. # Buat Destinasi Webhook API > Daftarkan destinasi webhook Didit baru dengan versi, event berlangganan, dan rahasia penandatanganan khusus. Operasi webhook terprogram, bayar per panggilan. Buat Prompt API Destinasi Webhook Salin prompt ke papan klip \

\`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.`

\
Tempel ke Destinasi webhook memungkinkan Anda mengirim event Didit yang berbeda ke URL yang berbeda. Setiap destinasi memiliki `secret_shared_key`, `webhook_version`, dan daftar `subscribed_events` sendiri.## Cara kerja `subscribed_events``subscribed_events` adalah array wajib berisi nama event yang tepat. Didit hanya mengirimkan webhook ke destinasi ini ketika `webhook_type` pada payload cocok dengan salah satu nilai dalam array tersebut.- Sertakan setidaknya satu event. - Gunakan hanya nama event yang didukung di bawah ini. - Tambahkan setiap event yang ingin Anda terima; tidak ada nilai wildcard seperti `*` atau `all`. - Untuk mengarahkan area produk yang berbeda ke sistem yang berbeda, buat beberapa destinasi dengan daftar `subscribed_events` yang berbeda.## Katalog event| Event | Berlangganan saat Anda membutuhkannya | | - | - | | `status.updated` | Status sesi Verifikasi Pengguna (KYC) atau Verifikasi Bisnis (KYB) berubah. Payload KYB menyertakan `session_kind: "business"` dan `business_session_id`. | | `data.updated` | Data verifikasi sesi dikoreksi atau diperbarui setelah dibuat, misalnya saat peninjau mengedit data KYC, Bukti Alamat, atau KYB. | | `user.status.updated` | Status entitas Pengguna berubah, misalnya `ACTIVE`, `FLAGGED`, atau `BLOCKED`. | | `user.data.updated` | Profil, penghitung, metadata, dokumen, atau kolom verifikasi agregat entitas Pengguna berubah. | | `business.status.updated` | Status entitas Bisnis berubah, misalnya setelah peninjauan manual, hasil KYB, atau tindakan daftar blokir. | | `business.data.updated` | Profil, penghitung, metadata, kolom registrasi, atau kolom verifikasi agregat entitas Bisnis berubah. | | `activity.created` | Diterima di `subscribed_events` dan tercakup oleh **Try Webhook**, tetapi Didit saat ini tidak mengirimkannya untuk trafik live. | | `transaction.created` | Transaksi Pemantauan Transaksi dibuat dan evaluasi aturan awalnya selesai. | | `transaction.status.updated` | Status transaksi berubah setelah aturan, tinjauan analis, remediasi, pembaruan penyedia, atau tindakan API/konsol; juga dikirim sekali ketika skrining kripto yang dicoba ulang di latar belakang selesai. | | `travel_rule.status.updated` | Status pertukaran [Travel Rule](https://docs.didit.me/id/transaction-monitoring/travel-rule.md) berubah. | | `workflow.compliance_changed` | Status kepatuhan alur kerja yang dipublikasikan berubah setelah evaluasi ulang. | | `transaction_rule_suggestions.created` | Sebuah proses saran aturan mengusulkan perubahan aturan baru. |Keluarga event Investigator (`investigator.*`) dan Authentication (`auth.*`) juga diterima. Setiap event dan payload-nya tercantum di [Webhooks](https://docs.didit.me/id/integration/webhooks.md#jenis-event).Kumpulan langganan umum:```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" ] } ```Untuk contoh payload dan kode penandatanganan, lihat [panduan webhook](https://docs.didit.me/id/integration/webhooks.md). ## OpenAPI ````yaml id/openapi-25.json POST /v3/webhook/destinations/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API Verifikasi Identitas. Lakukan autentikasi dengan header x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/destinations/: post: tags: - Webhook summary: Buat tujuan webhook description: >- Buat tujuan webhook. Respons mencakup rahasia penandatanganan HMAC `secret_shared_key` yang dibuat secara otomatis (juga dapat dibaca nanti melalui `GET /v3/webhook/destinations/{destination_uuid}/`). Selalu kirim `subscribed_events` dengan setidaknya satu event webhook (tanpa karakter wildcard): daftar kosong eksplisit akan ditolak dengan 400, dan meniadakan kolom ini akan membuat tujuan yang tidak berlangganan apa pun, yang tidak akan pernah menerima webhook. Pasangan `(application, url)` harus unik di antara tujuan milik aplikasi. operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Nama yang mudah dibaca manusia yang ditampilkan di Console → Webhooks. Membantu membedakan tujuan ketika Anda memiliki beberapa (mis. "Prod", "Staging mirror"). url: type: string format: uri description: >- URL HTTPS yang akan menerima permintaan `POST`. Harus unik di antara tujuan aplikasi. Gunakan endpoint yang stabil dan diperkuat: Didit mencoba lagi pengiriman yang gagal dengan jadwal backoff. maxLength: 2000 enabled: type: boolean default: true description: >- Jika `false`, tujuan disimpan tetapi Didit tidak akan mengirim webhook apa pun ke sana. Berguna untuk konfigurasi staging yang ingin Anda simpan sementara. webhook_version: type: string enum: - v1 - v2 - v3 description: >- Versi skema payload yang akan dikirim oleh Didit. `v3` adalah format saat ini/yang direkomendasikan; versi yang lebih lama dipertahankan untuk kompatibilitas mundur dengan integrasi lama. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- Event untuk dikirimkan. Secara praktis wajib: `[]` eksplisit ditolak dengan 400, dan tidak menyertakan kolom ini akan membuat tujuan tanpa langganan yang tidak menerima apa pun. examples: session_updates: summary: Pembaruan data dan status sesi value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: Pembaruan pemantauan transaksi 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: Pembaruan entitas Pengguna dan Bisnis 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: >- Tujuan dibuat. `secret_shared_key` adalah rahasia penandatanganan HMAC — simpan sekarang. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: >- Pengidentifikasi tujuan yang stabil. Gunakan sebagai `{destination_uuid}` dalam panggilan berikutnya. 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: >- Rahasia penandatanganan HMAC yang dibuat secara otomatis dan terikat ke tujuan ini (token 43 karakter yang aman untuk URL). Gunakan ini untuk memverifikasi header tanda tangan pada webhook yang masuk. Selalu dikembalikan lengkap untuk pemanggil dengan kunci API; pengguna Console memerlukan izin `read:webhooks`, jika tidak, mereka melihat string kosong. secret_last4: type: string description: >- Empat karakter terakhir dari rahasia penandatanganan tujuan saat ini, sehingga Anda dapat membedakan rahasia. Tidak cukup untuk memverifikasi tanda tangan. previous_secret_expires_at: type: string format: date-time nullable: true description: >- Ditetapkan selama 24 jam setelah rahasia penandatanganan tujuan dirotasi di Business Console. Hingga waktu ini, setiap pengiriman ke tujuan juga membawa `X-Signature-Previous`, `X-Signature-V2-Previous`, dan `X-Signature-Simple-Previous`, yang dibuat dengan rahasia yang diganti (lihat [Verifikasi tanda tangan](/id/integration/webhooks#verifikasi-tanda-tangan)). `null` jika tidak ada rotasi yang terjadi dalam 24 jam terakhir. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- Email anggota Business Console yang membuat tujuan. `null` untuk tujuan yang dibuat dengan kunci API. created_by_name: type: string nullable: true description: >- Nama anggota Business Console yang membuat tujuan. Bernilai `null` untuk tujuan yang dibuat dengan kunci API. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- Status pengiriman. `failing`: 3 event berturut-turut atau lebih gagal pada upaya pengiriman pertamanya sejak tujuan terakhir kali merespons dengan berhasil (lihat `failing_streak`). `degraded`: tidak gagal (failing), tetapi upaya pengiriman gagal dalam 24 jam terakhir dan tidak ada upaya berikutnya yang berhasil mengirimkan event tersebut; percobaan ulang atau pengiriman ulang yang berhasil menyelesaikannya akan menghapus status ini. `healthy`: tidak keduanya. Independen dari `enabled`. Upaya yang gagal adalah upaya yang direspons dengan HTTP 400 ke atas, atau tidak direspons sama sekali. failing_streak: type: integer description: >- Berapa banyak event berturut-turut yang gagal pada upaya pengiriman pertamanya sejak tujuan terakhir kali merespons dengan berhasil, dalam 30 hari terakhir. Coba lagi tidak dihitung, dan setiap upaya yang berhasil, termasuk coba lagi atau pengiriman ulang, mengakhiri rentetan tersebut. `0` jika tidak ada event yang gagal sejak keberhasilan terakhir. failing_since: type: string format: date-time nullable: true description: >- Waktu ketika upaya gagal pertama dari `failing_streak` saat ini dilakukan. `null` jika `failing_streak` bernilai `0`. last_success_at: type: string format: date-time nullable: true description: >- Waktu ketika tujuan terakhir kali merespons pengiriman dengan status HTTP di bawah 400, dalam 30 hari terakhir. `null` jika tidak merespons dalam rentang waktu tersebut. environment: type: string enum: - live - sandbox description: Lingkungan aplikasi yang memiliki tujuan tersebut. summary: type: object description: >- Metrik pengiriman selama `metrics_window_days` (30) hari terakhir. `last_delivery_at` adalah upaya paling baru, kapan pun upaya tersebut dilakukan. 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: >- Panjang dalam hari dari jendela yang dicakup oleh metrik ringkasan lainnya. Selalu `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: >- Validasi gagal — biasanya URL duplikat, `subscribed_events` tidak ada/tidak valid, atau nama event tidak dikenal. 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: >- Kunci API tidak ada, format salah, kedaluwarsa, atau memiliki cakupan untuk aplikasi yang berbeda. Kunci yang tidak ada mengembalikan `403`; kunci yang salah, dicabut, atau kedaluwarsa mengembalikan `401`. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '429': description: Batas laju terlampaui; lakukan back off dan coba lagi. 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: >- Filter event untuk tujuan webhook ini. Didit hanya mengirimkan webhook yang tipe event-nya sama persis dengan salah satu nilai ini — tidak ada langganan wildcard. Saat dikirim, daftar ini harus berisi setidaknya satu event yang valid (`[]` eksplisit akan ditolak dengan kode 400); tujuan yang daftarnya kosong (kolom tidak disertakan saat pembuatan) tidak akan menerima apa pun. Saat pembaruan, daftar diganti secara keseluruhan, tidak pernah digabungkan. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated WebhookEvent: type: string description: >- Nama event webhook yang didukung. Gunakan string persis ini di `subscribed_events`; nilai yang tidak didukung akan ditolak. 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: >- Kunci API aplikasi Anda, dari Developers -> API keys di Business Console. Kunci utama memiliki akses penuh. Kunci bernama dapat diberi cakupan: none, read, atau write per sumber daya, dibatasi pada beberapa alur kerja atau pada sesi yang disetujui, pada daftar alamat IP, dan pada tanggal kedaluwarsa. 401 berarti kuncinya salah, dicabut, atau kedaluwarsa; 403 berarti tidak ada kunci yang dikirimkan, kunci tidak memiliki akses ke sumber daya atau tindakan ini, atau permintaan datang dari alamat di luar daftar IP-nya; 404 pada rute sesi berarti sesi berada di luar alur kerja atau status kunci tersebut. Kunci tanpa akses media menerima URL gambar, video, dan PDF sebagai null, dan kunci tanpa izin tulis sesi menerima tautan sesi dan token sebagai null. Lihat https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.