Webhook API KYB: Event, Payload & Tanda Tangan

Webhook KYB Didit memberi tahu backend Anda saat sesi verifikasi bisnis berubah status, atau saat peninjau atau registri mengubah datanya. Entitas bisnis memiliki event sendiri. Berlangganan ke event yang Anda perlukan melalui API tujuan webhook atau Business Console.

Katalog event

Event sesi digunakan bersama oleh sesi Pengguna dan sesi Bisnis. Kolom session_kind pada payload menunjukkan jenis sesi yang dirujuk event tersebut. Event tingkat entitas terpisah dari event tingkat sesi.

Event tingkat sesi

Event	Kapan dipicu
`status.updated`	Status sesi berubah. Untuk sesi Verifikasi Bisnis (KYB), payload membawa `session_kind: "business"`. Ini adalah event yang perlu dipantau untuk melihat kemajuan.
`data.updated`	Peninjau mengedit data registri, melewati atau membuat ulang Pihak Kunci di konsol, atau registri melaporkan perubahan (jika pemantauan registri tersedia). Kolom `trigger` menunjukkan penyebabnya.

data.updated tidak dikirim saat pemohon mengunggah dokumen atau mengirimkan Pihak Kunci, atau saat pemindaian ulang AML selesai. Gunakan status.updated atau ambil keputusan sesi untuk memantau kemajuan tersebut.

Event entitas bisnis

Event	Kapan dipicu
`business.status.updated`	Status entitas Bisnis yang terhubung berubah (`ACTIVE` / `FLAGGED` / `BLOCKED`).
`business.data.updated`	Kolom profil atau penghitung agregat entitas Bisnis berubah.

Berlangganan ke kombinasi event apa pun pada tujuan webhook Anda. Lihat webhook entitas untuk referensi lengkap event entitas Bisnis / Pengguna.

Bentuk payload

Webhook sesi menggunakan payload datar, tanpa pembungkus data. Struktur pembungkus, header tanda tangan, dan setiap kolom bersama didokumentasikan dalam referensi webhook. Sesi KYB menambahkan kolom-kolom berikut:

Kolom	Tipe	Deskripsi
`session_kind`	`"business"`	Memungkinkan handler generik membedakan KYC dan KYB.
`business_session_id`	`uuid`	Sama dengan `session_id`.
`vendor_business_id`	string	Pengenal Anda untuk entitas Bisnis, jika diberikan saat sesi dibuat.
`status`	string	Label persis, misalnya `"In Progress"`, `"Approved"` atau `"Awaiting User"`. Lihat status.
`trigger`	string	Opsional. Alasan webhook dipicu. Pada `data.updated` untuk KYB: `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` atau `"kyb_registry_change"`.
`decision`	object	Ada saat `status` bernilai `Approved`, `Declined`, `In Review` atau `Abandoned`. Bentuknya sama dengan `GET /v3/session/{id}/decision/`, lihat skema respons.
`resubmit_info`	object	Ada saat `status` bernilai `Resubmitted`.

`status.updated` untuk sesi KYB

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}

Blok decision memuat registry_checks[], key_people_checks[], document_verifications[], aml_screenings[] dan array KYB lainnya.

`data.updated` untuk sesi KYB

data.updated membawa struktur pembungkus datar yang sama dengan status.updated, ditambah trigger yang menjelaskan alasan event dipicu. Saat status sesi Approved, Declined, In Review atau Abandoned, event ini juga membawa decision terkini. Ambil ulang keputusan untuk melihat apa yang berubah. Payload tidak memiliki daftar changed_fields.

`business.status.updated` dan `business.data.updated`

Event entitas juga datar. Event ini membawa vendor_business_id, vendor_data, status (ACTIVE, FLAGGED atau BLOCKED) dan created_at. business.status.updated menambahkan previous_status. business.data.updated menambahkan changed_fields dan peta changes berbentuk { field: { previous, current } }.

{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}

Verifikasi tanda tangan

Setiap webhook ditandatangani dengan HMAC-SHA256 menggunakan rahasia bersama milik tujuan webhook Anda. Verifikasi isi permintaan mentah dengan header X-Signature-V2 (direkomendasikan) dan tolak pengiriman yang X-Timestamp-nya sudah berusia lebih dari 300 detik. Referensi webhook mencantumkan semua header tanda tangan, periode tumpang tindih rotasi rahasia penandatanganan, dan contoh kode.

Kebijakan coba lagi

Respons 5xx atau 404, waktu habis, atau kegagalan koneksi memicu hingga 2 kali coba lagi, masing-masing setelah sekitar 1 menit dan sekitar 4 menit, lalu pengiriman dibuang.
Respons 4xx dan 3xx lainnya tidak dicoba lagi.
Setiap coba lagi mempertahankan event_id yang sama, sehingga Anda dapat menghapus duplikat berdasarkan nilai tersebut.
Anda dapat mengirim ulang pengiriman dari log pengiriman tujuan. Referensi webhook memuat kebijakan lengkapnya.

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

Untuk memfilter sesi bisnis di sisi Anda, periksa session_kind === "business" di dalam event status.updated dan data.updated.

Langkah selanjutnya

Referensi webhook

Tujuan, penandatanganan, coba lagi, pola umum.

Status

Referensi status sesi dan fitur.

Skema respons

Mendekode payload keputusan KYB.

Memulai

Fitur

Profil Bisnis

Referensi

Konsol

Webhook API KYB: Event, Payload & Tanda Tangan

Katalog event

Event tingkat sesi

Event entitas bisnis

Bentuk payload

`status.updated` untuk sesi KYB

`data.updated` untuk sesi KYB

`business.status.updated` dan `business.data.updated`

Verifikasi tanda tangan

Kebijakan coba lagi

Berlangganan

Langkah selanjutnya

Referensi webhook

Status

Skema respons

​Katalog event

​Event tingkat sesi

​Event entitas bisnis

​Bentuk payload

​status.updated untuk sesi KYB

​data.updated untuk sesi KYB

​business.status.updated dan business.data.updated

​Verifikasi tanda tangan

​Kebijakan coba lagi

​Berlangganan

​Langkah selanjutnya

Referensi webhook

Status

Skema respons

Katalog event

Event tingkat sesi

Event entitas bisnis

Bentuk payload

`status.updated` untuk sesi KYB

`data.updated` untuk sesi KYB

`business.status.updated` dan `business.data.updated`

Verifikasi tanda tangan

Kebijakan coba lagi

Berlangganan

Langkah selanjutnya