Webhook #

Webhook memungkinkan Your AI Connector untuk secara otomatis memberi tahu alat bisnis Anda yang lain setiap kali terjadi sesuatu yang penting — kontak baru dibuat, janji temu dipesan, atau pesan diterima. Alih-alih memeriksa pembaruan secara manual, sistem Anda yang terhubung akan mendapatkan pemberitahuan instan saat sesuatu terjadi.

Apa Itu Webhook? #

Bayangkan webhook seperti pesan teks otomatis antara dua aplikasi. Saat sesuatu terjadi di Your AI Connector (seperti pendaftaran kontak baru), platform akan langsung mengirimkan pemberitahuan ke sistem lain pilihan Anda. Anda memberikan alamat web (disebut “URL webhook”) tempat pemberitahuan ini harus dikirim — ini biasanya disediakan oleh CRM, platform otomatisasi, atau pengembang Anda.

Webhook hanya mengirim data KELUAR dari Your AI Connector. Webhook adalah jalan satu arah dari Your AI Connector ke alat Anda yang lain. Tidak ada URL webhook yang mengirim prospek, kontak, atau pesan KE DALAM platform. Untuk memasukkan prospek baru — dari formulir situs web, CRM Anda, atau GoHighLevel — sistem Anda melakukan panggilan API sebagai gantinya. Lihat Akses API (operasi Buat Kontak) dan Corong. Satu-satunya hal yang Anda perlukan untuk arah masuk adalah kunci API Anda, yang berada di bagiannya sendiri — lihat Akses API. Halaman Webhook yang dijelaskan di sini khusus untuk arah keluar.

Penggunaan umum meliputi:

• Menyinkronkan kontak baru ke CRM Anda.
• Memicu alur kerja di Zapier, Make, atau Pabbly saat tag diterapkan.
• Memberi tahu tim Anda di Slack saat manusia diberi peringatan.
• Memperbarui sistem kalender Anda saat janji temu dipesan.
• Mencatat ringkasan percakapan ke basis data Anda.

Menyiapkan Webhook #

1. Di bilah sisi kiri, klik Pengaturan (ikon roda gigi).
2. Di bilah sisi Pengaturan, di bawah grup Integrasi, klik Webhook.

Pada akun yang belum dikonfigurasi webhook-nya, halaman akan terlihat seperti ini:

3. Klik New webhook, di kanan atas. Formulir akan terbuka secara inline di halaman tersebut:

4. Isi:
   • URL Endpoint — alamat web tempat Your AI Connector akan mengirimkan pemberitahuan peristiwa. Anda mendapatkan ini dari sistem eksternal Anda (CRM, platform otomatisasi, atau server kustom).
   • Nama — label yang akan Anda kenali nanti (misalnya “Peringatan Slack” atau “Sinkronisasi CRM”). Hanya untuk referensi Anda.

URL webhook Anda harus berupa alamat https:// yang dapat dijangkau publik. Alamat http:// biasa, localhost atau alamat jaringan pribadi, dan alamat internal platform akan ditolak saat Anda menyimpan. Untuk menguji dari mesin Anda sendiri, gunakan tunnel publik (webhook.site atau ngrok) alih-alih localhost.

5. Di bawah Events, klik peristiwa yang ingin Anda terima oleh webhook ini — ke-22 peristiwa tersebut tercantum dalam The 22 Webhook Events.
6. (Opsional) Aktifkan Retry failed deliveries jika Anda ingin Your AI Connector terus mencoba saat terjadi kegagalan sementara — lihat Retrying Failed Deliveries.
7. Klik Create webhook. Webhook akan muncul di daftar di bawah formulir, dan Anda dapat mengeklik Test pada barisnya kapan saja untuk mengirim payload contoh ke endpoint Anda.

Izin diperlukan. Menambah, mengedit, atau menguji webhook memerlukan izin “edit” Integrasi (anggota tim dengan akses lihat-saja akan melihat pemberitahuan baca-saja alih-alih formulir).

Menandatangani webhook mengharuskan webhook tersebut sudah disimpan terlebih dahulu — buka baris webhook yang ada untuk mengeditnya, dan panel Rahasia penandatanganan akan muncul di bagian bawah formulir edit. Draf baru yang belum disimpan belum memiliki opsi penandatanganan — lihat Payload yang Ditandatangani di bawah.

Satu Webhook untuk Semua Akun Klien Anda (Agensi) #

Jika Anda menjalankan agensi, Anda tidak perlu membuat ulang webhook yang sama di setiap akun klien. Pada akun agensi, formulir webhook memiliki tombol alih tambahan: Juga aktifkan untuk semua akun klien. Aktifkan tombol ini dan webhook ini juga akan menerima acara yang terjadi di setiap akun klien di bawah agensi Anda — satu endpoint, seluruh agensi.

Cara kerjanya:

• Blok user memberi tahu Anda milik siapa acara tersebut. Setiap notifikasi sudah membawa blok user yang mengidentifikasi akun tempat acara tersebut terjadi, sehingga otomatisasi Anda dapat melakukan perutean per klien.
• Pengaturan webhook Anda sendiri berlaku di mana saja. Acara yang Anda pilih, rahasia penandatanganan, dan pengaturan coba lagi juga digunakan untuk pengiriman akun klien.
• Tidak ada pengiriman ganda. Jika akun klien memiliki webhook sendiri yang mengarah ke URL yang sama, webhook tersebut yang akan digunakan untuk acara akun itu — acara yang sama tidak akan pernah tiba dua kali di satu endpoint.
• Klien tidak melihatnya. Webhook tersebut tidak muncul di halaman Webhook milik akun klien, dan klien tidak dapat mematikannya — webhook tersebut sepenuhnya di bawah kendali Anda.
• Keandalan dilacak per akun klien. Jika endpoint Anda terus gagal, webhook akan dimatikan secara otomatis untuk akun yang pengirimannya gagal (lihat Keandalan Webhook), bukan untuk seluruh agensi sekaligus.

Tombol alih ini hanya muncul di akun agensi. Pengaturan melalui API juga didukung — lihat kolom apply_to_sub_accounts di API Webhook.

Acara Pemicu yang Tersedia #

Anda dapat mengaktifkan atau menonaktifkan masing-masing dari 22 peristiwa webhook secara independen. Saat suatu peristiwa dipicu, Your AI Connector mengirimkan notifikasi ke URL webhook Anda dengan data yang relevan. Setiap peristiwa, artinya, dan kode event yang dimasukkannya ke dalam payload tercantum bersama dalam The 22 Webhook Events di bagian bawah halaman ini.

Perlu diketahui: Task Created, Task Updated, dan Task Completed dapat dipilih sepenuhnya dan disimpan dengan benar. Daily Summary Created juga merupakan tambahan baru. Lihat Task Completed Webhook di bawah untuk bentuk payload tersebut.

Pemicu Webhook Berbasis Tag #

subscribed_to_tags tidak membatasi peristiwa webhook ke tag tertentu. Ini hanya mempersempit tag mana yang menghasilkan notifikasi ringkasan percakapan. Untuk mendapatkan permintaan saat tag tertentu diterapkan, atur URL webhook pada tag tersebut di tab Tags pada agen (atau kampanye).

Formulir webhook itu sendiri tidak memiliki pemilih tag, baik saat membuat webhook baru maupun saat mengeditnya, sehingga subscribed_to_tags hanya dapat dibaca atau diubah melalui Webhooks API, atau dengan meminta bantuan dukungan.

Perlu diketahui: mengedit webhook yang sudah ada yang memiliki daftar subscribed_to_tags (mengganti nama, mengubah peristiwanya, mengaktifkan/menonaktifkan percobaan ulang) tidak lagi menghapus daftar tersebut — karena formulir tidak memiliki pemilih tag untuk dikirim kembali, menyimpan dari halaman ini sekarang membiarkan daftar yang ada tidak tersentuh. (Ini adalah bug nyata sebelum 21 Juli 2026: menyimpan dari formulir webhook dulu menghapus daftar karena selalu mengirim daftar tag kosong. Jika webhook kehilangan daftar subscribed_to_tags-nya sebelum tanggal tersebut, webhook perlu dikonfigurasi ulang melalui API.)

Hasilkan Ringkasan untuk Kontak yang Ditandai #

Jika webhook memiliki daftar subscribed_to_tags, Anda dapat mengaktifkan Generate Summary. Saat diaktifkan, Your AI Connector secara otomatis membuat ringkasan percakapan untuk kontak tersebut saat salah satu tag tersebut diterapkan, dan menyertakannya dalam data webhook — konteks lengkap tanpa perlu permintaan terpisah.

Menguji Webhook Anda #

1. Buka Pengaturan → Integrasi → Webhook.
2. Pada baris webhook Anda, klik Uji.
3. Periksa sistem eksternal Anda untuk memastikan data pengujian telah diterima.
4. Tinjau format data untuk memastikan sistem Anda dapat mengurainya dengan benar.

Untuk pengujian menyeluruh dari awal hingga akhir, kirim pesan yang akan memicu salah satu peristiwa yang telah Anda konfigurasi (siaran, atau pesan masuk di saluran yang terhubung) dan verifikasi bahwa webhook aktif dengan data yang sebenarnya.

Apa yang Dianggap sebagai Pengiriman Berhasil #

Baik Anda mengeklik Test atau peristiwa tersebut benar-benar dipicu, kami mengirimkan hal yang sama:

• Permintaan POST (bukan GET), dengan isi sebagai JSON dan Content-Type: application/json.
• Header yang tercantum di bawah Signed Payloads. Header tanda tangan hanya disertakan setelah Anda menetapkan rahasia penandatanganan (signing secret).

Kami menganggap pengiriman berhasil jika:

• Endpoint Anda menjawab dengan status 2xx apa pun (200, 201, 204 — semuanya baik).
• Menjawab dalam waktu 30 detik.

Beberapa hal yang mengejutkan orang:

• Isi respons diabaikan. Anda tidak perlu mengembalikan JSON tertentu. Respons 200 kosong sudah cukup.
• Pengalihan (redirect) dihitung sebagai kegagalan. Kami tidak mengikuti pengalihan, jadi 301 atau 302 (termasuk pengalihan garis miring di akhir, atau http ke https) dicatat sebagai pengiriman yang gagal. Simpan URL akhir, bukan URL yang mengalihkan.
• String kueri didukung sepenuhnya. https://your-app.com/hook?token=abc123 dikirim persis seperti yang Anda simpan, jadi menempatkan token di string kueri berfungsi sama baiknya dengan menempatkannya di jalur.
• URL Anda harus https:// dan dapat dijangkau secara publik. Alamat yang termasuk dalam infrastruktur Your AI Connector sendiri akan ditolak, tetapi endpoint Anda sendiri di Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting, atau tempat lain tidak masalah.
• Firewall atau lapisan perlindungan bot di depan endpoint Anda dapat memblokir kami. Kasus yang paling umum adalah Cloudflare: jika zona Anda mengaktifkan Bot Fight Mode atau tantangan terkelola, permintaan kami akan mendapatkan halaman tantangan “Just a moment…” dengan status 403 alih-alih mencapai server Anda — dan permintaan server-ke-server tidak akan pernah bisa melewati tantangan browser, jadi tombol Test dan peristiwa nyata akan gagal dengan cara yang sama. Tombol Test akan memberi tahu Anda saat hal ini terjadi (“Cloudflare is showing a bot challenge to our request”). Perbaiki di Cloudflare dengan aturan Keamanan / WAF yang melewati tantangan untuk jalur webhook Anda (atau untuk agen pengguna Webhook-Delivery/1.0), lalu klik Test lagi.
• Jika firewall Anda memerlukan daftar izin IP sebagai gantinya (misalnya paket gratis Cloudflare, di mana Bot Fight Mode biasa tidak dapat dilewati oleh aturan WAF, tetapi Aturan Akses IP yang diatur ke Izinkan berjalan sebelumnya), kami dapat membantu: setiap pengiriman, baik dari tombol Test atau peristiwa langsung, dikirim dari satu alamat IPv4 tetap (tanpa rentang, tanpa IPv6, tanpa rotasi). Hubungi dukungan dan kami akan memberikan alamat untuk dimasukkan ke daftar izin. Tetap gunakan verifikasi tanda tangan sebagai pemeriksaan kepercayaan Anda yang sebenarnya, karena verifikasi ini memvalidasi setiap payload terlepas dari mana asalnya.
• Hasil Test memberi tahu Anda dengan tepat apa yang dijawab oleh endpoint Anda. Tes yang gagal sekarang menunjukkan alasan sebenarnya (status HTTP yang dikembalikan endpoint Anda, waktu habis, atau bahwa kami tidak dapat menjangkau alamat tersebut sama sekali) alih-alih kesalahan umum, dan tes pada webhook yang disimpan dikirim dengan tanda tangan saat penandatanganan aktif, persis seperti peristiwa langsung.

Menggunakan n8n, Make, atau Zapier (“Test URL” vs “Production URL”) #

Platform otomatisasi biasanya memberikan dua alamat webhook yang berbeda, dan hal ini sering membingungkan pengguna:

• URL Uji (di n8n berisi /webhook-test/). URL ini hanya menerima data saat Anda sedang aktif memantau kanvas dan baru saja mengeklik Dengarkan peristiwa uji (atau Uji alur kerja). URL ini menangkap satu peristiwa lalu berhenti mendengarkan — jadi mengeklik Uji di Your AI Connector beberapa kali berturut-turut hanya akan menangkap yang pertama, dan hanya jika jendela pendengaran aktif pada saat yang tepat itu. Untuk menguji: klik Dengarkan peristiwa uji di n8n terlebih dahulu, lalu kembali ke Your AI Connector dan klik Uji sekali.
• URL Produksi (di n8n berisi /webhook/, tanpa -test). Ini adalah URL yang harus ditempelkan ke Your AI Connector untuk peristiwa langsung. URL ini hanya berfungsi setelah alur kerja Anda diaktifkan (Active). Jika alur kerja tidak aktif, n8n akan menolak permintaan dengan kesalahan “404 / webhook not registered”, meskipun Your AI Connector telah mengirimkan data dengan benar.

Singkatnya: uji dengan URL Uji saat mendengarkan, tetapi agar webhook terus berfungsi pada kontak nyata, simpan URL Produksi di Your AI Connector dan pastikan alur kerja dalam status Active.

Format Data Webhook #

Saat webhook dipicu, Your AI Connector mengirimkan data terstruktur (JSON) ke URL webhook Anda. Jika Anda menggunakan platform otomatisasi seperti Zapier atau Make, platform tersebut akan mengurai data ini untuk Anda secara otomatis. Jika Anda membangun integrasi kustom:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

campaign atau agent — biasanya salah satu, bukan keduanya. Jika akun Anda menggunakan agen, kontak Anda berada di bawah agen, bukan kampanye, sehingga campaign muncul sebagai null dan agent memberi tahu Anda siapa yang menanganinya. Akun berbasis kampanye yang lebih lama melihat kebalikannya. Baca bagian mana pun yang terisi; jangan berasumsi campaign selalu ada.

Blok agent tiba pada 15 Agustus 2026. Blok ini bersanding dengan campaign pada peristiwa yang terkait dengan percakapan — obrolan yang selesai, jangan ganggu, lanjutkan, batal arsip, jeda AI, pesan baru, ringkasan percakapan, dan webhook yang dapat Anda atur pada tag — serta membawa id dan name agen penangan, atau null jika tidak ada agen yang terlibat. Ini murni bersifat tambahan: setiap bidang yang sudah Anda terima tidak berubah, sehingga penerima yang Anda buat sebelum tanggal tersebut tetap berfungsi tanpa perlu pembaruan apa pun.

Beberapa peristiwa menambahkan blok tingkat atas tambahan mereka sendiri. Misalnya, Appointment Booked menambahkan blok appointment (lihat Webhook Appointment Booked), New Message menambahkan blok message lengkap dengan teksnya (lihat Webhook New Message), dan Deliveries serta Reads menambahkan blok message singkat yang hanya berisi ID dan status pesan (lihat Webhook Deliveries and Reads).

Deliveries dan Reads memberi tahu Anda pesan mana, tetapi bukan apa isinya. Keduanya membawa blok message yang berisi id dan status pesan tersebut — dan id tersebut sama dengan messageId yang dikembalikan oleh endpoint kirim pesan, sehingga Anda dapat mencocokkan tanda terima pengiriman atau pembacaan dengan pesan persis yang Anda kirim — tetapi tidak ada isi pesan. Replies tidak membawa blok message sama sekali. Jika Anda memerlukan kata-kata yang dikirim atau diterima, berlanggananlah ke New Message bersamaan dengan peristiwa tersebut.

Dua hal yang perlu diketahui sebelum Anda menulis penerima. Tidak ada bidang timestamp, dan tidak ada pembungkus data. Setiap blok berada di tingkat atas objek JSON, seperti yang ditunjukkan di atas.

The 22 Webhook Events #

22 peristiwa webhook, dengan label tampilan yang Anda centang di aplikasi dan kode event yang dikirim dalam payload. Kode event adalah string pendek yang tidak cocok dengan label tampilan, jadi sesuaikan penerima Anda berdasarkan kodenya, bukan labelnya:

Dua kode lagi tidak pernah muncul dalam daftar itu karena Anda tidak berlangganan: contact_tags_updated, dikirim oleh URL webhook yang diatur pada tag individu, dan summary_generated, dikirim saat ringkasan obrolan ditulis untuk tag dalam daftar subscribed_to_tags webhook.

Saluran Terhubung belum dikirim. Ini muncul di daftar acara, tetapi tidak ada yang memicunya saat ini. Jangan membangun integrasi berdasarkan ini.

Notifikasi berbasis tag dan tugas menggunakan bentuknya sendiri yang terpisah. Lihat Contact Tags Updated dan Task Completed.

Webhook Kontak Dibuat #

Dikirim saat peristiwa Kontak Dibuat aktif (kontak baru ditambahkan secara manual, melalui impor, atau melalui API).

Nama peristiwa #

contactCreated

Format payload #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Sampel “Uji” dan peristiwa nyata terlihat sedikit berbeda. Tombol uji mengirimkan data placeholder (John Doe, kampanye sampel). Peristiwa Kontak Dibuat yang nyata membawa detail kontak yang sebenarnya, dan beberapa bidang mungkin kosong tergantung pada saluran.

Webhook Pesan Baru #

Webhook ini dipicu setiap kali pesan ditambahkan ke percakapan, di saluran mana pun. Ini mencakup kedua arah: pesan yang dikirim kontak kepada Anda, dan pesan yang dikirim AI, tim Anda, atau kampanye kepada mereka. Ini adalah satu-satunya webhook yang menyertakan teks pesan, jadi ini adalah webhook yang digunakan saat Anda ingin mencerminkan percakapan ke sistem eksternal.

Nama peristiwa #

new_message

Format payload #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web"
  }
}

Masih belum ada blok campaign dalam payload ini. Pesan Baru mengirimkan contact, agent, user, dan message. Blok agent ditambahkan pada 15 Agustus 2026 dan memberi tahu Anda agen mana yang menangani percakapan; jika Anda juga memerlukan konteks kampanye, cari kontak tersebut melalui API menggunakan contact.id.

Catatan AI internal tidak memicu webhook ini. Selain pesan nyata, platform menyimpan baris pembukuan sendiri dalam percakapan (panggilan alat AI dan catatan giliran internal). Hal tersebut tidak pernah dikirim — Anda hanya menerima pesan yang benar-benar dikirim atau diterima.

Webhook Deliveries and Reads #

Kedua peristiwa ini melaporkan apa yang terjadi pada pesan setelah meninggalkan Your AI Connector: Deliveries terpicu saat pesan mencapai kontak (atau gagal mencapainya), dan Reads terpicu saat kontak membukanya, pada saluran yang mendukung tanda terima telah dibaca.

Keduanya membawa blok message dengan ID pesan yang dimaksud oleh peristiwa tersebut, sehingga Anda dapat mencocokkan pembaruan dengan pesan persis yang Anda kirim.

Nama peristiwa #

delivered dan undelivered untuk Deliveries, read untuk Reads.

Format payload #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Cara mencocokkan pembaruan dengan pesan yang Anda kirim. Simpan messageId yang Anda dapatkan saat mengirim pesan melalui API. Saat notifikasi Deliveries atau Reads tiba, cari ID yang disimpan tersebut terhadap message.id di payload — itulah tanda terima pengiriman atau pembacaan Anda untuk pesan persis tersebut.

Tidak ada teks pesan di sini. Blok message hanya membawa ID dan status. Berlanggananlah ke New Message jika Anda juga memerlukan isi pesannya.

Blok message hanya ada jika kami mengetahui pesan mana itu. Pada pembaruan langka yang tidak dapat kami kaitkan kembali ke pesan yang disimpan, blok tersebut ditinggalkan sepenuhnya daripada dikirim kosong — jadi periksa apakah message ada sebelum membaca message.id.

Satu notifikasi per perubahan status. Satu pesan keluar biasanya menghasilkan notifikasi delivered dan kemudian, pada saluran dengan tanda terima telah dibaca, notifikasi read. Pengiriman yang gagal menghasilkan undelivered sebagai gantinya.

Webhook Appointment Booked #

Aktif saat kontak memesan janji temu. Peristiwa ini aktif dengan cara yang sama baik saat AI memesannya selama percakapan, Anda memesannya secara manual, atau melalui API.

Nama peristiwa #

booked

Format payload #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id sering kali null dalam webhook ini, dan itu normal. Peristiwa Google Calendar dibuat pada saat yang sama dengan notifikasi ini keluar, jadi ID biasanya belum siap. Ambil kembali janji temu berdasarkan appointment_id-nya beberapa saat kemudian jika Anda membutuhkannya. ID tersebut akan tetap null secara permanen jika akun tidak memiliki Google Calendar yang terhubung, jadi jangan menunggu selamanya.

Tombol “Uji” tidak menyertakan blok appointment. Gunakan tombol tersebut untuk mengonfirmasi bahwa endpoint Anda merespons, lalu buat satu pemesanan nyata untuk melihat payload lengkapnya.

Dua kasus di mana webhook ini tidak aktif: janji temu yang diimpor dari kalender eksternal, dan pemesanan yang masuk melalui integrasi Formitable.

Webhook Pembaruan Tag Kontak #

Terpicu saat sebuah tag diterapkan ke kontak, dan tag tersebut memiliki URL webhook yang dikonfigurasi pada agen atau kampanye tempat kontak tersebut berada.

Nama peristiwa #

contact_tags_updated

Kapan webhook ini dipicu #

• Tag diterapkan ke kontak yang memiliki agen yang ditugaskan, kampanye yang ditugaskan, atau keduanya.
• Setidaknya salah satu tag yang diterapkan memiliki URL webhook yang diatur di tab Tag pada agen atau kampanye tersebut.

Jika kontak memiliki keduanya dan tag kampanye membawa URL webhook, tag tersebut yang digunakan; jika tidak, tag agen yang akan digunakan.

Jika beberapa tag dengan URL webhook yang berbeda diterapkan dalam pembaruan yang sama, satu permintaan akan dikirim per URL, masing-masing hanya berisi tag yang dipetakan ke URL tersebut.

Menghapus tag tidak akan pernah mengirimkan permintaan. Kebanyakan orang mengarahkan URL ini ke suatu tindakan — mengumpulkan deposit, memesan slot, memberi tahu perwakilan — sehingga tag yang dihapus dari kontak tidak lagi digunakan untuk menjalankan ulang tindakan tersebut. Penghapusan masih muncul di removed_tags jika terjadi dalam pembaruan yang sama dengan penerapan yang menuju ke URL yang sama, sehingga otomatisasi yang membaca kedua array tetap mendapatkan gambaran lengkap; yang tidak akan pernah dilihatnya adalah permintaan yang disebabkan oleh penghapusan saja. (Diubah pada 12 Agustus 2026. Sebelum tanggal tersebut, penghapusan juga mengirimkan permintaan.)

Format payload #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    }
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Menguji webhook tag #

Di samping kolom URL webhook pada tab Tag terdapat tombol Uji. Tombol ini akan segera mengirimkan payload sampel ke URL tersebut, sehingga Anda dapat memastikan otomatisasi Anda menerimanya sebelum menunggu percakapan yang sebenarnya.

Pengujian mengirimkan bentuk contact_tags_updated yang sama seperti yang ditunjukkan di atas, menggunakan kontak placeholder, dengan tag yang sedang Anda uji di added_tags dan removed_tags kosong. Apa yang dilihat otomatisasi Anda dalam pengujian adalah apa yang akan dilihatnya dalam produksi.

Dua hal yang perlu diketahui:

• Simpan tag terlebih dahulu. Tes mencari tag berdasarkan nama yang disimpan, jadi tag baru atau perubahan nama yang belum disimpan belum dapat diuji. Tombol tetap berwarna abu-abu sampai nama di layar cocok dengan yang disimpan.
• Tes yang gagal tidak dihitung terhadap webhook Anda. Tes tidak pernah berkontribusi pada penghentian otomatis setelah kegagalan berulang yang dijelaskan dalam Webhook Reliability.

Jika pengujian gagal, pesan akan memberi tahu Anda apa yang dijawab oleh endpoint Anda (misalnya 404 atau 500), yang biasanya cukup untuk menemukan URL yang salah atau alur kerja yang belum diaktifkan.

Webhook Tugas Selesai #

Hanya untuk referensi. Webhook tugas (sebagai data) didokumentasikan di sini untuk pengembang; peristiwa Task Created, Task Updated, dan Task Completed dapat dipilih dalam daftar peristiwa standar pada formulir webhook seperti peristiwa lainnya — lihat Available Trigger Events dan The 22 Webhook Events.

Payload ini dikirim saat tugas beralih ke tahap yang ditandai sebagai tahap penyelesaian. Tugas yang berpindah antar tahap non-penyelesaian akan mengirimkan bentuk taskUpdated sebagai gantinya.

Nama peristiwa #

taskCompleted

Kapan webhook ini dipicu #

• Tugas diperbarui.
• Nilai stage-nya berubah dibandingkan dengan nilai sebelumnya.
• Tahap baru dikonfigurasi sebagai tahap penyelesaian pada pengaturan tahap tugas akun.

Format payload #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Mematikan (atau Menghapus) Webhook #

Setiap webhook memiliki tombol on/off, tepat di barisnya. Mematikan (off) webhook akan menghentikan penerimaan peristiwa, tetapi tetap menyimpan semua konfigurasi Anda — URL, peristiwa, dan rahasia penandatanganan apa pun. Nyalakan kembali dan webhook akan berlanjut dari titik terakhirnya; tidak ada peristiwa yang terjadi selama webhook dimatikan yang akan dikirimkan setelahnya.

Gunakan fitur ini saat Anda ingin menghentikan pengiriman untuk sementara: endpoint Anda sedang dibangun ulang, Anda sedang men-debug integrasi yang terlalu bising, atau Anda sedang menjeda otomatisasi.

Menghapus webhook (ikon tempat sampah di barisnya) akan menghilangkannya secara permanen, termasuk rahasia penandatanganannya. Jika Anda hanya ingin menghentikan pengiriman, matikan saja webhook tersebut — hapus hanya digunakan jika Anda sudah benar-benar selesai dengan endpoint tersebut.

Ini tidak sama dengan webhook yang dimatikan secara otomatis. Jika kami menonaktifkan webhook Anda setelah kegagalan berulang (lihat Keandalan Webhook), tombol di atas tidak akan mengaktifkannya kembali. Setelah endpoint Anda diperbaiki, edit webhook tersebut dan simpan dengan URL yang diubah (perubahan URL apa pun akan mengaktifkannya kembali), atau panggil endpoint aktifkan kembali melalui API — atau hubungi dukungan dan kami akan mengaktifkannya kembali untuk Anda.

Payload Bertanda Tangan (Memverifikasi Bahwa Webhook Benar-benar Berasal dari Kami) #

Siapa pun yang mengetahui URL webhook Anda dapat mengirimkan permintaan palsu palsu ke URL tersebut. Jika Anda menindaklanjuti webhook secara otomatis — memperbarui penagihan, membuat catatan CRM — mengaktifkan penandatanganan memungkinkan Anda memverifikasi bahwa setiap permintaan benar-benar berasal dari kami.

Penandatanganan bersifat opsional dan dinonaktifkan secara default, dan Anda dapat mengaktifkannya per webhook, dari tampilan edit webhook tersebut (buka baris webhook yang tersimpan).

Mengaktifkan penandatanganan #

1. Buka webhook (Pengaturan → Integrasi → Webhook → klik baris webhook Anda).
2. Di bagian Signing secret, klik Generate.
3. Salin secret tersebut (diawali dengan whsec_) dan simpan di sistem penerima Anda. Perlakukan secret ini seperti kata sandi.

Anda dapat kembali dan menampilkan, menyalin, merotasi, atau menonaktifkan secret kapan saja dari panel yang sama ini.

Apa yang kami kirimkan #

Setelah penandatanganan aktif, setiap pengiriman untuk webhook tersebut membawa dua header HTTP tambahan ini:

Ketiga header ini ada pada setiap pengiriman, baik ditandatangani maupun tidak:

Cara memverifikasi #

Tanda tangan adalah HMAC-SHA256 dari string <timestamp>.<raw request body>, menggunakan secret penandatanganan Anda sebagai kuncinya.

Verifikasi terhadap badan permintaan mentah — byte yang tepat yang Anda terima. Jika framework Anda mengurai JSON dan membuat serialisasi ulang sebelum memeriksa, byte tersebut dapat berubah dan tanda tangan tidak akan cocok.

Contoh Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

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

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Contoh Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Bandingkan tanda tangan dengan fungsi yang aman dari timing (timingSafeEqual / compare_digest), bukan ==. Ini tidak memakan biaya dan menghindari kelas serangan yang halus.

Merotasi secret #

Klik Putar untuk mengganti rahasia. Pergantian terjadi seketika: pengiriman berikutnya hanya ditandatangani dengan rahasia baru. Jika endpoint Anda aktif, terimalah baik rahasia lama maupun baru selama beberapa menit saat Anda menerapkan yang baru.

Mematikan penandatanganan hanya akan menghentikan pengiriman header tanda tangan.

Mencoba Ulang Pengiriman yang Gagal #

Secara default, pengiriman yang gagal tidak akan dicoba ulang — jika sistem Anda sedang tidak aktif pada saat itu, peristiwa tersebut akan terlewatkan.

Aktifkan Coba ulang pengiriman yang gagal pada webhook (di formulir buat/edit) dan kami akan terus mencoba:

Itu mencakup sekitar 2 jam 40 menit, sehingga webhook dapat bertahan selama jendela pemeliharaan atau gangguan singkat di pihak Anda.

Apa yang dicoba ulang: masalah sementara — server Anda mengembalikan kesalahan 5xx, timeout, atau kegagalan koneksi.

Apa yang tidak dilakukan: jika endpoint Anda menolak permintaan itu sendiri (4xx apa pun), kami tidak akan mencoba ulang — mengirimkan permintaan yang identik lagi hanya akan menghasilkan penolakan yang identik.

Acara mana yang dicoba ulang: webhook tag (contact_tags_updated), tiga acara tugas, dan ringkasan harian. Sisanya dikirim sekali, jadi untuk acara tersebut sakelar tidak memiliki fungsi apa pun. Setiap acara tetap membawa X-Webhook-Delivery, sehingga satu aturan deduplikasi mencakup semuanya.

Aktifkan percobaan ulang hanya jika endpoint Anda bersifat idempoten. Percobaan ulang berarti peristiwa yang sama dapat tiba lebih dari sekali. Gunakan header X-Webhook-Delivery untuk mengenali pengulangan: header tersebut tetap sama di setiap upaya untuk satu peristiwa, sehingga Anda dapat dengan aman mengabaikan ID yang sudah Anda tangani.

Percobaan ulang berinteraksi dengan fitur nonaktif otomatis setelah kegagalan berulang (lihat Keandalan Webhook) sesuai keinginan Anda: penghitung kegagalan menghitung satu pengiriman utuh, hanya setelah setiap percobaan ulang digunakan — bukan setiap upaya individu.

Keandalan Webhook #

• Your AI Connector mengirim webhook melalui koneksi aman (HTTPS). Pastikan alamat web yang Anda berikan menggunakan HTTPS.
• Jika sistem Anda mengembalikan kesalahan, pengiriman dianggap gagal.
• Pantau waktu aktif sistem penerima Anda agar tidak melewatkan peristiwa.
• Untuk alur kerja penting, aktifkan Mencoba Ulang Pengiriman yang Gagal, dan pertimbangkan juga mekanisme cadangan.

Webhook dimatikan secara otomatis setelah kegagalan berulang. Jika URL webhook Anda gagal berulang kali (sekitar 5 kesalahan berturut-turut, atau 3 berturut-turut untuk kesalahan tipe konfigurasi), Your AI Connector secara otomatis berhenti mengirimkan peristiwa ke URL tersebut. Untuk mengaktifkannya kembali setelah endpoint Anda sehat: edit webhook tersebut dan simpan dengan URL yang diubah (perubahan URL apa pun akan mengaktifkannya kembali), atau gunakan endpoint aktifkan kembali melalui API — menyimpan kembali dengan URL yang sama tidaklah cukup. Dukungan juga dapat mengaktifkannya kembali untuk Anda.

Pemecahan Masalah #

Langkah Selanjutnya #

• Integrasi GoHighLevel — gunakan webhook untuk mengintegrasikan Your AI Connector dengan GHL.
• Akses API — gabungkan webhook dengan API untuk otomatisasi yang canggih.
• Menggunakan Tag untuk Melabeli Kontak — siapkan tag yang memicu webhook Anda.