Copy page

Pengaturan

Outgoing Webhooks

Ringkasan

Outgoing Webhooks memungkinkan admin menghubungkan OmniStream ke sistem eksternal — CRM pihak ketiga, helpdesk, spreadsheet, Zapier, atau integrasi kustom — dengan cara berlangganan event yang terjadi di platform. Setiap event yang cocok dengan daftar langganan akan menghasilkan sebuah HTTP POST request ke URL yang Anda tentukan, lengkap dengan payload JSON dan signature HMAC-SHA256 untuk verifikasi.

Halaman pengaturan berada di rute /outgoing-webhooks.

Event types yang didukung

OmniStream v1 mem-publish enam event utama (plus contact.created opsional). Setiap webhook berlangganan ke satu atau lebih event:

Event Type	Dipicu saat
message.received	Pesan masuk (inbound) tersimpan di database
message.sent	Pesan keluar (outbound) berhasil dikirim
message.status	Status pesan keluar berubah (sent → delivered → read atau failed)
conversation.created	Percakapan baru dibuat di sistem
conversation.resolved	Status percakapan diubah menjadi resolved
conversation.assigned	Percakapan ditugaskan ke agent (baik otomatis maupun manual)

Enam event di atas adalah kontrak publik — admin tidak perlu mengaktifkannya satu per satu di backend; cukup berlangganan lewat UI. Jika subsistem memproduksi event yang tidak berlangganan oleh satupun webhook, backend tidak akan menuliskan delivery row (efisiensi).

Headers yang dikirim

Setiap delivery POST request menyertakan header berikut:

Header	Nilai	Catatan
Content-Type	application/json	Payload selalu JSON
X-Omnistream-Event	mis. message.received	Memudahkan routing di sisi penerima tanpa parsing body
X-Omnistream-Signature	HMAC-SHA256 hex-encoded dari seluruh body menggunakan secret webhook	Untuk verifikasi autentisitas

Contoh verifikasi di sisi penerima (Node.js):

Code
import crypto from 'node:crypto';

function verify(body, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  // Gunakan timingSafeEqual untuk mencegah timing attack
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Retry & exponential backoff

Jika endpoint penerima mengembalikan status non-2xx atau timeout, dispatcher akan melakukan retry dengan exponential backoff. Delay setiap attempt berkembang dengan pengali 4: 30 * 4^(attempt-1) detik.

Perilaku default (max_attempts = 3)

Secara default, dispatcher mencoba mengirim 3 kali total (2 retries):

Attempt	Waktu eksekusi	Jika gagal
1	Segera setelah event muncul	Tunggu 30 detik (formula: 30 * 4^0 = 30)
2	30 detik setelah attempt 1 gagal	Tunggu 120 detik (formula: 30 * 4^1 = 120)
3	120 detik setelah attempt 2 gagal	attempt >= max_attempts → permanent failure

Menaikkan max_attempts

max_attempts dapat dikonfigurasi per-webhook lewat pengaturan webhook di UI. Berikut referensi delay untuk attempt lanjutan:

Attempt	Delay sebelum attempt berikutnya	Formula
1	30 detik	30 * 4^0
2	120 detik (2 menit)	30 * 4^1
3	480 detik (8 menit)	30 * 4^2
4	1920 detik (32 menit)	30 * 4^3
5	7680 detik (~2 jam)	30 * 4^4

Dengan default max_attempts = 3, attempt 3 adalah yang terakhir dan delay 480 detik tidak dipakai.

Retry manual

Admin dapat melihat delivery history per-webhook di panel Activity Log dan menekan tombol Retry manual jika endpoint sudah pulih. Granularitas minimum delay efektif adalah 30 detik.

Langkah-langkah

Membuat webhook baru

1. Buka /outgoing-webhooks dari sidebar.
2. Klik + New Webhook.
3. Isi form:
   • Name — label internal, mis. Zapier Integration Production
   • URL — endpoint HTTPS tujuan
   • Secret — string rahasia untuk HMAC signature (simpan juga di sisi penerima)
   • Events — pilih satu atau lebih dari 6 event type
   • Is Active — centang untuk mengaktifkan
4. Klik Save. Backend memanggil POST /api/outgoing-webhooks (tag Outgoing Webhooks).

Menguji webhook

1. Klik ikon Play di baris webhook.
2. Backend akan mengirim payload dummy ke URL dan menampilkan hasil (status code, body, durasi).
3. Periksa sisi penerima apakah signature cocok.

Memeriksa riwayat delivery

1. Klik ikon Eye atau buka tab Activity Log.
2. Daftar delivery menampilkan: timestamp, event type, URL, status code, attempt count, dan body respons.
3. Filter berdasarkan status (pending, success, failed, cancelled) tersedia di atas tabel.
4. Klik baris untuk mengembang (expand) dan melihat payload lengkap.

Menonaktifkan atau menghapus

1. Ikon pensil untuk mengedit (mis. menambah/menghapus event dari langganan).
2. Ikon trash untuk menghapus permanent. Delivery history yang belum dieksekusi akan di-cancel.

Endpoint (tag Outgoing Webhooks)

Aksi	Endpoint
List webhook	GET /api/outgoing-webhooks
Detail	GET /api/outgoing-webhooks/{id}
Buat webhook	POST /api/outgoing-webhooks
Update webhook	PUT /api/outgoing-webhooks/{id}
Hapus webhook	DELETE /api/outgoing-webhooks/{id}
Test webhook	POST /api/outgoing-webhooks/{id}/test
List delivery history	GET /api/outgoing-webhooks/{id}/deliveries
Retry delivery manual	POST /api/outgoing-webhooks/deliveries/{id}/retry
List event types	GET /api/outgoing-webhooks/event-types

Skema lengkap di API Reference — Outgoing Webhooks.

Praktik terbaik

• Gunakan HTTPS, bukan HTTP, untuk URL tujuan.
• Selalu verifikasi X-Omnistream-Signature sebelum memproses payload — ini satu-satunya cara memastikan payload berasal dari OmniStream.
• Balas cepat di sisi penerima (≤ 1 detik) dan lakukan pemrosesan lama di background queue Anda sendiri, untuk menghindari timeout yang memicu retry.
• Simpan secret di environment variable, bukan di source code.
• Monitor failed deliveries — > 5% gagal menandakan endpoint atau jaringan tidak stabil.

Rute terkait

• Activity Logs — audit perubahan konfigurasi webhook