osFoundry / Platform
Webhook masuk
URL per aplikasi atau workspace untuk menerima event. Verifikasi tanda tangan sudah terpasang.
Apa itu
Webhook masuk memberi osFoundry sebuah alamat penerima bagi dunia luar. Anda membuat token yang dibatasi ke app, instance, dan channel tertentu, lalu osFoundry mengembalikan URL khusus di bawah /api/v1/webhooks/inbound/{id}. Sistem eksternal (Stripe, GitHub, Zapier, pipeline CI, backend Anda sendiri) mem-POST JSON ke URL itu, dan event tersebut mendarat di channel realtime yang Anda pilih, tempat chat, agen, dan app Anda dapat menindaklanjutinya. Tidak ada polling dan tidak ada server integrasi terpisah yang perlu dijalankan: endpoint itulah integrasinya.\n\nVerifikasi tanda tangan sudah tertanam, bukan tempelan belakangan. Setiap token membawa secret penanda tangan HMAC-SHA256, yang ditampilkan tepat sekali saat dibuat. Pengirim menghitung tanda tangan atas payload dan mengirimkannya di header X-OsFoundry-Signature; osFoundry memvalidasinya pada setiap permintaan dan menolak apa pun yang tidak bertanda tangan atau diubah dalam perjalanan. Ketika Anda perlu mengganti kunci sebuah pengirim, merotasi secret membuka jendela toleransi 7 hari yang selama itu secret sebelumnya masih valid, sehingga rotasi tidak pernah membuang event yang sedang berjalan. Mencabut token bersifat langsung: endpoint segera mulai mengembalikan 401, jalur cepat untuk menghadapi secret yang bocor atau integrasi yang dipensiunkan.\n\nKarena ini berjalan di dalam workspace desktop BYOK osFoundry, sebuah event masuk dapat memicu agen, app, dan pengetahuan yang sama yang sudah Anda gunakan, tanpa pajak integrasi per kursi dan tanpa data Anda memutar lewat perantara pihak ketiga. Setiap token melacak waktu pemakaian terakhir dan jumlah permintaan 24 jam sehingga Anda bisa melihat pengirim mana yang aktif, dan platform menyimpan 100 permintaan masuk terakhir untuk di-replay, yang mengubah debugging webhook dari menebak-nebak menjadi menjalankan ulang payload yang sebenarnya.
Kemampuan utama
- Buat URL penerima khusus per app, instance, dan channel: sistem eksternal mem-POST event JSON langsung ke endpoint itu di bawah /api/v1/webhooks/inbound/{id}
- Setiap permintaan diverifikasi terhadap tanda tangan HMAC-SHA256 di header X-OsFoundry-Signature, sehingga payload tak bertanda tangan atau yang diutak-atik ditolak sebelum mencapai channel Anda
- Rotasi secret penanda tangan dengan jendela toleransi 7 hari yang membuat secret lama masih valid, agar Anda bisa mengganti kunci pengirim tanpa kehilangan event
- Cabut token seketika: endpoint mengembalikan 401 pada saat pencabutan, memutus pengirim yang bocor atau yang sudah tak dipakai
- Lihat waktu pemakaian terakhir dan jumlah permintaan 24 jam per token, serta replay 100 permintaan masuk terakhir dari pengaturan trigger saat Anda perlu men-debug sebuah pengiriman
Kasus penggunaan
- Developer yang menyambungkan Stripe: membuat token yang dibatasi ke channel penagihan, mengarahkan webhook Stripe ke URL itu, dan membiarkan osFoundry menolak POST mana pun yang tanda tangan HMAC-nya tidak cocok sebelum mencapai agen
- Ops engineer dengan secret bocor: mencabut token yang terdampak untuk 401 seketika lalu membuat yang baru, tanpa menjatuhkan integrasi lain yang memasok workspace
- Pembangun otomasi yang menghubungkan pipeline CI: mem-POST event status build ke channel tempat agen memilah kegagalan, memakai replay 100 permintaan terakhir untuk men-debug bentuk payload
Pertanyaan yang sering diajukan
Bagaimana osFoundry memverifikasi bahwa sebuah webhook masuk itu asli?
Setiap token masuk memiliki secret penanda tangan HMAC-SHA256. Pengirim menghitung tanda tangan atas body permintaan dan mengirimkannya di header X-OsFoundry-Signature, lalu osFoundry menghitung ulang dan membandingkannya pada setiap permintaan. Permintaan dengan tanda tangan yang hilang atau tidak valid ditolak, jadi hanya sistem yang memegang secret yang bisa mempublikasikan ke channel Anda. Secret ditampilkan sekali saat pembuatan: simpan saat itu juga, karena ia tidak ditampilkan lagi setelahnya.
Apa yang terjadi pada event yang sedang berjalan ketika saya merotasi atau mencabut token?
Rotasi memberi Anda jendela toleransi 7 hari yang selama itu secret baru dan lama sama-sama valid, sehingga Anda bisa memperbarui setiap pengirim tanpa kehilangan event selama peralihan. Pencabutan sengaja dibuat kebalikannya: endpoint mengembalikan 401 seketika, memutus pengirim saat itu juga, persis yang Anda inginkan bila sebuah secret bocor atau sebuah integrasi dipensiunkan.
Apakah saya mendapat satu URL webhook untuk semuanya, atau bisa dibatasi cakupannya?
Setiap token dibatasi ke app, instance, dan channel tertentu, dan membuat URL-nya sendiri di bawah /api/v1/webhooks/inbound/{id}. Artinya satu pengirim tidak bisa mempublikasikan ke channel yang tak diberikan kepadanya, dan Anda bisa mencabut atau merotasi satu integrasi tanpa menyentuh yang lain. Setiap token juga melaporkan waktu pemakaian terakhir dan jumlah permintaan 24 jam sehingga Anda tahu endpoint mana yang benar-benar menerima lalu lintas.