Ikhtisar webhook

Sursa mencatat peristiwa untuk setiap perubahan penting: kartu dipublikasikan, diverifikasi, atau diarsipkan, pengumuman dibaca, pertanyaan tidak terjawab. Anda dapat menerima peristiwa dengan dua cara, dan memakai keduanya bersama-sama:

Keduanya membawa peristiwa yang sama dengan ID yang sama. Setiap peristiwa disimpan di umpan selama 30 hari, terlepas dari ada atau tidaknya webhook yang berlangganan peristiwa itu.

Peristiwa

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

data hanya memuat apa yang dapat dilihat oleh pembaca objek mana pun melalui API. Field itu tidak pernah berisi daftar akses, izin orang lain, atau field tersembunyi. Alasan dalam peristiwa berupa kode netral yang singkat seperti no_hits, restricted, atau index_failed.

Jenis peristiwa

Peristiwa mencakup bidang-bidang berikut:

Daftar lengkap beserta skema dan contoh setiap peristiwa ada di katalog peristiwa di referensi API. GET /v1/webhooks/catalog mengembalikan jenis yang tersedia di instalasi Anda.

Jenis peristiwa baru ditambahkan dari waktu ke waktu, dan peristiwa yang ada mendapat field tambahan. Jenis peristiwa tidak pernah diganti namanya atau dihapus. Penerima Anda harus melewati jenis dan field yang tidak dikenalnya.

Siapa menerima apa

Webhook menerima peristiwa hanya jika objek peristiwa itu terlihat oleh webhook tersebut, dengan cara yang sama seperti bagi kunci API: menurut perannya, profil datanya, dan koleksinya. Webhook yang dibatasi pada koleksi support tidak pernah menerima peristiwa tentang kartu di finance. Peristiwa tentang orang, kunci, sumber, impor, job, ekspor, penagihan, aplikasi, dan webhook itu sendiri hanya dikirim ke webhook dengan peran admin.

Di dalam batas itu, setiap webhook memilih peristiwanya:

• menurut jenis, dengan pola: card.* untuk setiap peristiwa kartu, * untuk setiap peristiwa;
• menurut koleksi dan menurut tag, untuk peristiwa kartu.

Mode payload sebuah webhook adalah full (peristiwa dengan data, default) atau thin (peristiwa tanpa data: penerima Anda membaca objeknya melalui API dengan kuncinya sendiri, dan selalu melihat keadaan terkininya).

Pengiriman secara singkat

• POST HTTPS dengan peristiwa sebagai JSON, ditandatangani dengan rahasia webhook dalam dua format: Standard Webhooks (webhook-signature) dan X-KB-Signature yang lebih lama.
• Jawaban 2xx apa pun dalam 10 detik dianggap berhasil.
• Kegagalan dicoba ulang selama hampir tiga hari dengan jeda yang makin panjang. Retry-After dalam jawaban 429 atau 503 dihormati; 410 menonaktifkan webhook; 10 kegagalan berturut-turut menjeda webhook hingga dilanjutkan kembali.
• Pengiriman ke satu webhook dikirim dengan urutan yang ketat. Webhook yang lambat tidak menunda webhook lain.
• Peristiwa yang sama dapat tiba lebih dari sekali: buang duplikat menurut webhook-id.

Menerima webhook membahas penerima yang lengkap, dengan pemeriksaan tanda tangan dalam Node.js, Python, dan Go.

Mengelola webhook

Mengelola webhook membutuhkan kunci dengan peran admin dan cakupan webhooks:manage, atau administrator di antarmuka administrasi. Organisasi dapat memiliki hingga 20 webhook. Webhook adalah bagian dari paket organisasi; tanpa fitur itu, endpoint ini menjawab 403 dengan kode webhooks.feature_disabled.