Webhook (Outbound)
Mengirim event proses AlurKerja (process.started, task.assigned, task.completed, task.delegated) ke sistem Anda sendiri lewat HTTP webhook bertanda tangan, dari tab Webhook di Workspace Setting.
Outbound Webhook mendorong (push) event proses AlurKerja ke sistem Anda sendiri lewat HTTP webhook bertanda tangan, sehingga sistem eksternal (ERP, CRM, data lake, dsb.) tidak perlu terus-menerus melakukan polling. Setiap kali sebuah event terjadi — misalnya sebuah proses dimulai atau sebuah task di-assign — AlurKerja akan mengirim POST berisi data event ke URL yang Anda daftarkan.
Fitur ini diatur dari tab Webhook pada Workspace Setting, bersebelahan dengan tab Notification.
Tab Webhook adalah konfigurasi admin workspace, bukan setting end-user — subscription menyimpan signing secret. Anda membutuhkan role Owner atau Admin SOP untuk mengaksesnya.
Prasyarat
- Role Owner atau Admin SOP pada workspace.
- Sebuah endpoint penerima (receiver) yang dapat menerima HTTP
POSTdan membalas2xx. Untuk uji coba, Anda bisa memakai layanan seperti webhook.site. - Delivery worker aktif di environment (
ENABLE_WEBHOOK_DELIVERY_WORKER=true). Tanpa worker ini, subscription tetap bisa dibuat dan event tetap masuk antrian, tetapi statusnya berhenti di pending dan tidak pernah terkirim. Hubungi tim infra bila pengiriman tidak berjalan sama sekali.
Membuka Tab Webhook
- Dari sidebar Studio, buka Workspace Setting.
- Pilih tab Webhook.
Halaman Outbound Webhooks menampilkan seluruh subscription yang sudah ada. Setiap kartu menampilkan nama, transport (HTTP), status (Active/paused), badge Signed bila memakai signing secret, URL tujuan, daftar event, tanggal dibuat, serta tombol Deliveries, Edit, dan Delete.
Membuat Subscription
Klik Add Subscription. Sebuah panel (drawer) akan terbuka di sisi kanan.
Isi kolom berikut:
| Kolom | Keterangan |
|---|---|
| Name | Label untuk keperluan admin. Tidak dikirim ke subscriber. |
| Active | Bila menyala, event dikirim. Matikan untuk pause pengiriman tanpa menghapus subscription maupun riwayatnya. |
| Target URL | Setiap event di-POST ke sini. Respons 2xx dihitung terkirim; selain itu akan di-retry. |
| Signing secret | Kunci untuk menandatangani setiap pengiriman. Kosongkan agar sistem membuatkan secret otomatis (disarankan). |
| Events | Pilih event yang ingin dilangganani. Selama tidak ada yang dipilih, tidak ada yang dikirim. Gunakan Select all untuk memilih semua. |
Setelah lengkap, klik Create Subscription.
Daftar Event yang Tersedia
| Event | Kapan diterbitkan |
|---|---|
process.started | Sebuah process instance dimulai |
task.assigned | Sebuah user task di-assign ke user |
task.completed | Sebuah user task diselesaikan |
task.delegated | Sebuah user task di-delegate ke user lain |
Payload event membawa seluruh variable proses/task terkait secara utuh, sehingga subscriber menerima konteks lengkap tanpa perlu memanggil API tambahan.
Menyalin Signing Secret (Sekali Tampil)
Bila Anda membiarkan kolom Signing secret kosong, sistem membuatkan secret dan menampilkannya satu kali tepat setelah subscription dibuat.
Salin secret ini sekarang juga. Secret disimpan terenkripsi dan tidak akan pernah ditampilkan lagi. Jika hilang, satu-satunya jalan adalah me-rotate-nya (lihat Mengubah & Rotasi Secret). Simpan secret di tempat aman — jangan tampilkan di dokumentasi publik atau commit ke git.
Klik Copy untuk menyalin, lalu I saved it untuk menutup banner.
Memverifikasi Signature (HMAC)
Setiap pengiriman membawa dua header:
X-AlurKerja-Signature: v1=<HMAC-SHA256>X-AlurKerja-Timestamp: <unix-timestamp>
Signature dihitung dengan HMAC-SHA256 memakai signing secret Anda, atas string gabungan "<timestamp>.<body>" (timestamp, tanda titik, lalu body mentah). Di sisi penerima:
- Baca
X-AlurKerja-Timestampdan body mentah request. - Susun ulang string
"<timestamp>.<body>". - Hitung HMAC-SHA256 memakai signing secret, bandingkan dengan nilai pada
X-AlurKerja-Signature. - Tolak bila tidak cocok, atau bila timestamp sudah terlalu lama (mencegah replay attack).
Memantau Pengiriman (Deliveries)
Klik Deliveries pada sebuah subscription untuk melihat riwayat pengiriman.
Panel ini menampilkan setiap pengiriman beserta Event, Status, jumlah Attempts, waktu Queued dan Finished. Gunakan filter status di atas — All, Pending, Processing, Completed, Failed — dan tombol Refresh untuk memuat data terbaru.
| Status | Arti |
|---|---|
| Pending | Masih menunggu diproses worker |
| Processing | Sedang dikirim |
| Completed | Penerima membalas 2xx |
| Failed | Gagal setelah seluruh percobaan retry habis (kolom Attempts, misalnya 5/5). Kolom Status menampilkan penyebabnya, misalnya receiver responded 404. |
Replay — untuk pengiriman yang failed, klik Replay untuk mengantrikan ulang pengiriman tersebut. Replay hanya berlaku untuk delivery yang sudah gagal; baris pending/processing masih ditangani worker.
Mengubah & Rotasi Secret
Klik Edit pada subscription untuk mengubah nama, status Active, Target URL, daftar event, atau me-rotate secret.
- Rotate signing secret — kosongkan untuk mempertahankan secret yang sekarang. Isi hanya bila ingin mengganti secret; secret baru juga akan ditampilkan sekali setelah disimpan, dan secret lama langsung tidak berlaku. Keterangan "A signing secret is currently set" menandakan subscription sudah punya secret.
- Pause — matikan toggle Active untuk menghentikan pengiriman sementara tanpa kehilangan subscription maupun riwayatnya.
Klik Save Changes untuk menyimpan.
Menghapus Subscription
Klik Delete, lalu konfirmasi pada dialog.
Subscription beserta pengaturan per-event-nya dihapus dan tidak ada event yang dikirim lagi. Riwayat pengiriman yang lampau tetap disimpan.
Troubleshooting
| Yang terlihat | Penyebab paling mungkin | Cara memperbaiki |
|---|---|---|
| Semua delivery berstatus Pending dan tidak pernah terkirim | Delivery worker tidak aktif di environment | Aktifkan ENABLE_WEBHOOK_DELIVERY_WORKER=true (hubungi tim infra) |
Delivery Failed dengan receiver responded 404 | Target URL salah atau endpoint penerima sudah tidak ada (misalnya token webhook.site kedaluwarsa) | Perbaiki Target URL lewat Edit, lalu Replay delivery yang gagal |
| Delivery Failed dengan timeout / 5xx | Endpoint penerima down atau lambat | Pastikan penerima membalas 2xx dengan cepat; delivery akan otomatis di-retry |
| Signature tidak cocok di sisi penerima | Salah menyusun string yang ditandatangani | Tandatangani "<timestamp>.<body>" (bukan body saja), memakai signing secret yang benar |
| Signing secret hilang | Secret hanya tampil sekali saat dibuat | Rotate secret lewat Edit untuk mendapatkan yang baru |
| Tidak ada event yang terkirim padahal subscription aktif | Tidak ada event yang dipilih | Buka Edit, pilih minimal satu event, lalu Save |
Batasan yang Perlu Diketahui
- Transport yang tersedia saat ini adalah HTTP (webhook bertanda tangan). Setiap event dikirim sebagai
POSTke Target URL. - Signing secret tidak dapat dibaca ulang setelah dibuat — hanya bisa di-rotate.
- Pengiriman bergantung pada delivery worker. Bila worker mati, event tetap tercatat di antrian tetapi berhenti di status pending.