Webhook & Trigger

Trigger adalah cara Letaido mengetahui bahwa sesuatu terjadi di aplikasi lain, secara real time, tanpa harus terus memeriksa.

Ketika kontak baru masuk ke HubSpot, ketika seseorang @menyebut Anda di Slack, ketika deal berpindah tahap, Letaido langsung mengetahuinya dan bertindak.

Apa yang dapat Anda lakukan dengan ini

Hal-hal yang diatur tim di sini terlihat seperti:

• Ketika kontak HubSpot baru berstatus MQL, nilai mereka terhadap ICP kami dan posting hasilnya ke #mql-review.
• Ketika seseorang @menyebutkan bot Slack di #pmm-questions, jawab dengan suara merek kami.
• Ketika issue Linear diberi label customer-facing, buat draf ringkasan publik satu paragraf dan kirim DM ke pemimpin PMM.
• Ketika rilis GitHub dipublikasikan, buat draf otomatis email peluncuran dan kirim ke Notion untuk ditinjau.
• Ketika meeting Fathom selesai, ekstrak item tindakan dan tambahkan ke Linear.
• Ketika scraper Apify selesai, mulai tahap berikutnya dari pipeline.

Anda menjelaskan trigger dan tindakan dalam bahasa yang sederhana. Agen mengatur koneksi, meminta persetujuan sekali, lalu berjalan sendiri.

Cara kerjanya di balik layar

Ada dua jenis:

• Trigger konektor (disarankan). Langganan yang diketik ke layanan pihak ketiga. Pengaturan hanya memerlukan satu panggilan. Platform menangani langganan, rahasia penandatanganan, logika percobaan ulang, dan antrean event. Event tiba dengan skema yang diketahui (Slack, GitHub, Linear, HubSpot, Fathom, Apify, dan lainnya).
• Webhook ad-hoc. Untuk layanan yang belum memiliki trigger konektor bawaan, agen membuat URL webhook generik, mengonfigurasi pihak ketiga untuk POST ke URL tersebut, dan menarik event ke antrean yang sama. Biayanya adalah sedikit lebih banyak pekerjaan parsing, karena skemanya adalah apa pun yang dikirim oleh pihak ketiga.

Bagaimanapun, agen memilih yang tepat untuk Anda. Anda tidak memilih.

Bagaimana alur sebuah event

1. Layanan pihak ketiga melakukan POST ke URL publik yang dimiliki platform.
2. Platform memverifikasi tanda tangan, mengurai payload, memperkayanya (misalnya mengubah ID channel menjadi nama untuk Slack), dan mendorongnya ke antrian internal.
3. Konsumen (aplikasi, job, atau agen chat) melakukan polling antrian dengan kursor bernama dan memproses event.
4. Setiap event diakui setelah diproses; event yang tidak diakui akan dikirim ulang jika konsumen mengalami crash.

Cursor bersifat per-konsumen, sehingga aplikasi Console dan job dapat memantau event yang sama tanpa saling mengganggu.

Andal vs auto-ack

• Auto-ack (default). Baca event; event langsung hilang dari antrian. Sederhana. Cocok untuk "ikuti feed, catat ke tabel."
• Manual ack. Baca event, proses, lalu akui secara eksplisit. Jika pemrosesan gagal, event akan dikirim ulang. Gunakan ini ketika efek samping (email, penulisan database, panggilan API downstream) tidak boleh hilang.

Jika Anda meminta agen untuk "alur kerja yang andal," secara default agen akan memilih ack manual.

Bentuk umum permintaan

"Ketika kontak HubSpot baru dibuat dengan tahap siklus hidup = marketingqualifiedlead, nilai perusahaan tersebut terhadap ICP kami dan posting hasilnya ke #mql-review."

Agen: 1. Berlangganan Trigger pembuatan kontak HubSpot. 2. Menulis consumer kecil (aplikasi Console atau job) yang menarik event, memanggil ICP scorer, memposting ke Slack melalui konektor Slack. 3. Menampilkan persetujuan langganan HubSpot dan persetujuan Slack jika ini adalah penggunaan pertama dari permukaan tersebut.

"Ketika sebuah GitHub issue diberi label pmm-review, buat ringkasan satu paragraf yang menghadap pelanggan dan kirimkan DM kepada saya."

"Ketika seseorang @menyebut bot Slack di #pmm-questions, jawab menggunakan skill suara merek."

Yang Anda lihat di ruang kerja

Untuk setiap langganan aktif: - Connector dan jenis event. - Status signing secret. - URL publik (untuk ad-hoc) atau konfigurasi aplikasi pihak ketiga (untuk connector trigger). - Consumer yang membaca antrian.

Anda dapat menjeda atau mencabut langganan dari antarmuka ruang kerja. Mencabut akan mengembalikan 410 untuk setiap POST masuk selanjutnya.

Batas dan kasus tepi

• Tidak ada event yang pernah "fan-out dari chat." Trigger digerakkan oleh server. Jika sesi chat ditutup, event tetap tiba dan menumpuk di antrian hingga konsumen membacanya.
• Antrian memiliki jendela retensi. Event yang tidak terbaca lebih dari beberapa hari akan dihapus. Jika Anda menduga konsumen sedang offline, periksa sebelum mengasumsikan event terlewat.
• Konsumen situs publik dibatasi lebih ketat. Trigger permukaan situs memerlukan tinjauan eksplisit per panggilan (tidak ada persetujuan menyeluruh), karena alur yang dikontrol pengunjung merupakan risiko biaya fan-out.
• Rahasia penandatanganan disimpan, tidak pernah ditampilkan. Agen dapat menggunakannya tetapi tidak dapat membacanya kembali.

Di balik layar. Event masuk mengenai nginx → api-proxy → connectors service. Service memverifikasi tanda tangan terhadap signing secret yang tersimpan, menjalankan enrich hook konektor (misalnya resolver user-ID ke user-name Slack), kemudian menulis baris ke dalam webhook_events. Konsumen menarik melalui GET /webhooks/events?cursor=<name> dengan parameter provider dan ack opsional. Konsumen manual-ack melakukan POST kembali ke /webhooks/ack dengan through_id.