Webhooks

Webhook Konektor mengirim event secara asynchronous ketika perubahan lead terjadi. Delivery menggunakan queue, sehingga integrasi Anda harus mengasumsikan model at-least-once delivery.

Header Webhook

Setiap request webhook menyertakan header:

1. Content-Type: application/json
2. X-Konektor-Signature: t=<unix_timestamp>,v1=<hex_hmac_sha256>
3. X-Konektor-Event: <event_name>
4. User-Agent: Konektor-Webhook/1.0

Event yang Dikirim

Event utama pada flow lead:

1. lead.created
2. lead.updated

Payload body berisi objek event langsung (bukan envelope tambahan).

lead.created terkirim untuk setiap lead baru dari semua sumber, bukan hanya dari API dan dashboard. Field source menunjukkan asal lead:

Pengunjung yang hanya membuka halaman belum menjadi lead. Event lead.created terkirim saat pengunjung itu menjadi lead. Receiver Anda harus membuang duplikat berdasarkan lead.id.

Contoh lead.created

{
  "lead": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uniqueCode": "API_1A2B3C4D",
    "externalRef": "crm-001",
    "firstName": "Budi",
    "email": "budi@example.com",
    "phone": "6281234567890",
    "status": "new",
    "priority": "medium",
    "city": null,
    "country": null
  },
  "source": "api"
}

Contoh lead.updated

{
  "lead": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uniqueCode": "API_1A2B3C4D",
    "status": "qualified"
  },
  "leadId": "550e8400-e29b-41d4-a716-446655440000",
  "previousStatus": "new",
  "newStatus": "qualified",
  "changes": ["status"],
  "source": "api"
}

Event Inbox

Selain event lead di atas, Inbox mengirim enam event lewat webhook yang sama:

1. inbox.message.received
2. inbox.message.sent
3. inbox.message.status
4. inbox.conversation.owner_changed
5. inbox.conversation.handover
6. inbox.conversation.updated

Event inbox.conversation.handover terpicu saat asisten Agentic menyerahkan percakapan ke tim Anda. Payload-nya hanya berisi pengenal dan kode alasan, tanpa isi pesan atau nomor telepon:

{
  "event": "inbox.conversation.handover",
  "payload": {
    "conversation_id": "7c9ecb52-...",
    "reason": "customer_request",
    "assigned_to_user_id": "usr_182",
    "occurred_at": "2026-10-11T10:05:00.000Z"
  }
}

reason berisi salah satu dari keyword, max_replies, customer_request, sensitive_topic, upset, no_answer, atau other. assigned_to_user_id bernilai null jika tidak ada anggota tim yang menerima percakapan.

Event inbox.conversation.updated terpicu saat percakapan berubah: status, label, atau penanggung jawab baru, atau snooze yang berakhir. Webhook hanya menerimanya jika Anda memilihnya pada webhook itu. Payload-nya hanya berisi pengenal, status, dan ID label, tanpa isi pesan, nomor telepon, atau nama:

{
  "event": "inbox.conversation.updated",
  "payload": {
    "conversation_id": "7c9ecb52-...",
    "status": "resolved",
    "assigned_to_user_id": "usr_182",
    "label_ids": ["lbl_3", "lbl_7"],
    "occurred_at": "2026-10-11T10:07:00.000Z"
  }
}

Body event Inbox membungkus payload, berbeda dari event lead di atas yang mengirim payload langsung:

{
  "event": "inbox.message.received",
  "payload": { "...": "isi event" }
}

Header webhook, verifikasi signature, dan aturan idempotensi pada halaman ini berlaku sama untuk event Inbox. Contoh payload lengkap keenam event ada di Agent Inbox API.

Ubah, Jeda, dan Cek Webhook

Anda tidak perlu menghapus webhook untuk mengubahnya. Di Pengaturan > Lainnya > API & Webhooks, buka menu webhook lalu pilih Ubah webhook. Ubah alamat, event, atau kondisi, lalu pilih Simpan. Satu webhook dapat memilih beberapa event. Secret tetap sama.

Gunakan saklar pada webhook untuk menjedanya atau menyalakannya lagi. Webhook yang dijeda tidak menerima event sampai Anda menyalakannya.

Status pengiriman

Setiap webhook menampilkan waktu percobaan terakhirnya. Status menampilkan Gagal jika percobaan terakhir tidak berhasil. Pengiriman berikutnya yang berhasil menghapus status Gagal. Status lalu kembali Aktif.

Jeda retry

Saat event lead gagal, Konektor mencoba lagi sampai 5 kali. Jeda bertambah setelah setiap kegagalan: 15 detik, 30 detik, 1 menit, 2 menit, dan 4 menit. Setelah percobaan terakhir, Konektor berhenti mengirim event itu. Event Inbox mencoba ulang dengan jadwal terpisah.

Anda juga dapat mengelola webhook lewat Agent API dan dari Claude lewat connector Konektor.

Batas per Paket

Setiap workspace punya batas jumlah API key, webhook, dan webhook masuk. Paket menentukan batasnya. Setiap hitungan terpisah.

API key yang sudah dinonaktifkan atau kedaluwarsa tidak dihitung. Webhook masuk juga butuh paket yang mencakup API.

Saat batas tercapai, Konektor tidak membuat item baru. Hapus webhook yang tidak terpakai, atau nonaktifkan API key yang tidak terpakai. Anda juga dapat upgrade paket.

Alamat dan Secret Webhook

Webhook baru membutuhkan alamat https publik yang memakai nama domain. Konektor menolak alamat internal dan privat, seperti localhost, alamat di jaringan privat, dan alamat berakhiran .local atau .internal.

Setiap webhook punya secret untuk tanda tangan. Konektor menyimpan secret dalam bentuk terenkripsi. Daftar webhook hanya menampilkan 4 karakter terakhir. Pilih Tampilkan secret pada webhook untuk melihat secret lengkap dan menyalinnya.

Verifikasi Signature (Timing-Safe)

Gunakan raw body request saat menghitung HMAC. Jangan pakai body yang sudah di-parse lalu di-stringify ulang.

import crypto from 'node:crypto'

function verifyKonektorSignature(rawBody, signatureHeader, secret) {
  const parts = signatureHeader.split(',')
  const timestamp = parts.find(p => p.startsWith('t='))?.slice(2)
  const signature = parts.find(p => p.startsWith('v1='))?.slice(3)

  if (!timestamp || !signature) return false

  const now = Math.floor(Date.now() / 1000)
  if (Math.abs(now - Number(timestamp)) > 300) return false

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex')

  const providedBuf = Buffer.from(signature, 'hex')
  const expectedBuf = Buffer.from(expected, 'hex')

  if (providedBuf.length !== expectedBuf.length) return false
  return crypto.timingSafeEqual(providedBuf, expectedBuf)
}

Idempotensi

Webhook dikirim via queue dan bisa terkirim ulang saat retry. Endpoint Anda harus idempotent:

1. Simpan event key internal (misalnya kombinasi leadId + updatedAt + event).
2. Abaikan event duplikat yang sudah diproses.
3. Selalu balas 2xx jika event valid sudah pernah diproses.

Timeout dan Respons

Konektor mengirim webhook dengan timeout request singkat (5s). Endpoint receiver sebaiknya:

1. Validasi signature.
2. Enqueue pekerjaan berat ke worker internal.
3. Segera balas 200 OK.

Catatan Keamanan

1. Simpan webhook secret di server-side secret manager.
2. Untuk mengganti secret, buat webhook baru, pindahkan receiver Anda ke secret baru, lalu hapus webhook lama.
3. Tolak request tanpa header signature valid.
4. Terapkan allowlist IP jika infrastruktur Anda membutuhkannya.

Langkah berikutnya

• Integrasi CRM & Pihak Ketiga
• API Reference Overview
• Automation Rules