Webhook

Sebuah webhook mengirim permintaan HTTPS ke server Anda pada saat sesuatu terjadi di workspace Anda. Gunakan webhook alih-alih melakukan polling API: saat sebuah panggilan berakhir, Anda langsung menerima ringkasan, hasil, detail yang dikumpulkan, dan transkripnya. Setiap pengiriman ditandatangani dengan secret yang hanya diketahui Anda dan Ringhum, sehingga server Anda dapat menolak apa pun yang tidak berasal dari Ringhum.

Menambahkan endpoint

Hanya Pemilik dan Admin workspace yang dapat menambahkan, menguji, dan menghapus endpoint.

1. Buka Developer di sidebar.
2. Di kartu Webhook, klik Tambahkan endpoint.
3. Masukkan URL endpoint. Harus dimulai dengan https://.
4. Di bagian Event, centang event yang Anda inginkan. call.ended sudah dicentang untuk Anda.
5. Klik Tambahkan endpoint.
6. Salin signing secret dari kotak hijau (dimulai dengan whsec_) dan simpan di server Anda. Klik Selesai.

Penting: Signing secret hanya ditampilkan satu kali. Jika Anda kehilangannya, hapus endpoint tersebut dan tambahkan lagi untuk mendapatkan secret baru.

Anda dapat menambahkan sebanyak apa pun endpoint yang Anda butuhkan. Webhook mencakup setiap asisten di workspace. Anda juga dapat mengelola endpoint melalui API, dengan POST /webhooks dan sebuah kunci yang memiliki cakupan write.

Event

Bentuk sebuah pengiriman

Setiap pengiriman adalah sebuah POST dengan body JSON dan header berikut:

POST https://example.com/hooks/ringhum
Content-Type: application/json
User-Agent: Ringhum-Webhooks/1.0
X-Ringhum-Event: call.ended
X-Ringhum-Timestamp: 1789250000
X-Ringhum-Signature: v1=5f1a…

{
  "id": "evt_8f2k…",
  "type": "call.ended",
  "created_at": "2026-09-24T14:03:11+00:00",
  "data": {
    "call_id": 4812,
    "direction": "inbound",
    "from": "+14155550132",
    "to": "+14155550100",
    "assistant_id": 3,
    "status": "completed",
    "outcome": "message_taken",
    "sentiment": "neutral",
    "duration_seconds": 94,
    "summary": "Caller asked for a quote for a kitchen repair…",
    "extracted": { "name": "Dana Lee", "reason": "Quote" },
    "transcript": [
      { "role": "assistant", "content": "Hello, you've reached…" },
      { "role": "user", "content": "Hi, I'd like a quote…" }
    ]
  }
}

Objek data tergantung pada eventnya:

• call.ended dan message.taken: field panggilan di atas.
• call.started dan call.transferred: call_id, direction, from, to, assistant_id, status, dan started_at.
• appointment.*: appointment_id, title, status, starts_at, ends_at, timezone, customer (nama, telepon, email), contact_id, service, staff, call_id, dan notes.
• order.*: order_id, number, status, fulfillment, customer, address, items beserta opsi dan harganya, currency, subtotal, fee, total, source, call_id, dan, untuk pembatalan, cancel_reason.
• reservation.*: reservation_id, number, status, room, check_in, check_out, nights, adults, children, guest, currency, nightly, total, dan source.
• campaign.completed: campaign_id, name, dan hitungan kemajuan kampanye tersebut.

Catatan: Saat asisten membuat sebuah janji temu selama panggilan, Anda dapat menerima appointment.booked dua kali. Satu dikirim saat pemesanan dibuat, dengan field janji temu. Yang lain dikirim setelah panggilan diringkas, dengan field panggilan. Periksa apakah data memiliki appointment_id atau call_id dan gunakan field id untuk menghindari memproses sebuah pengiriman dua kali.

Memverifikasi tanda tangan

Tanda tangan tersebut adalah HMAC-SHA256 dari timestamp, sebuah titik, dan body permintaan mentah, dikunci dengan signing secret endpoint Anda. Dikirim sebagai v1= diikuti digest heksadesimalnya.

1. Baca body mentah persis seperti yang diterima, sebelum parsing JSON apa pun.
2. Bangun string {X-Ringhum-Timestamp}.{raw body}.
3. Hitung HMAC-SHA256 dengan secret Anda dan beri awalan v1=.
4. Bandingkan dengan X-Ringhum-Signature menggunakan perbandingan waktu konstan.
5. Tolak permintaan tersebut jika timestamp-nya lebih dari lima menit yang lalu, untuk memblokir permintaan yang diputar ulang.

Node.js:

const crypto = require('crypto');

function isValid(req, rawBody, secret) {
  const ts = req.header('X-Ringhum-Timestamp');
  const sig = req.header('X-Ringhum-Signature') || '';
  const expected = 'v1=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

PHP:

$ts = $_SERVER['HTTP_X_RINGHUM_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_RINGHUM_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . file_get_contents('php://input'), $secret);
if (! hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit;
}

Respons, batas waktu, dan percobaan ulang

• Balas dengan status 2xx apa pun untuk mengonfirmasi pengiriman. Lakukan pekerjaan yang lambat setelah Anda merespons.
• Ringhum menunggu hingga 10 detik untuk respons Anda.
• Jika endpoint Anda tidak menjawab dengan 2xx, pengiriman dicoba hingga 3 kali total: sekali segera, lagi setelah sekitar 10 detik, dan terakhir sekitar 60 detik kemudian. Setelah itu dibatalkan.
• Pengiriman dapat tiba tidak berurutan. Gunakan created_at dan id dalam data untuk mengurutkannya.

Tabel Webhook menampilkan status HTTP terakhir setiap endpoint dan kapan dikirim. Endpoint yang gagal tetap aktif; Ringhum tidak menonaktifkannya untuk Anda.

Menguji, menjeda, dan menghapus

• Kirim tes langsung mengirim sebuah event test.ping, dan sebuah pesan menampilkan status HTTP yang dikembalikan endpoint Anda.
• Saklar Aktif menjeda sebuah endpoint. Event yang terjadi saat nonaktif tidak dikirim kemudian.
• Hapus menghapus endpoint tersebut beserta secret-nya.

Pertanyaan umum

Apa bedanya dengan aplikasi Zapier, Make, dan n8n di bawah Integrasi? Koneksi tersebut menggunakan halaman Integrasi dan enam jenis eventnya. Body-nya adalah {"event", "workspace", "sent_at", "data"}, dan saat Anda mengatur sebuah secret, header tanda tangannya adalah X-Ringhum-Signature: sha256=…, sebuah HMAC-SHA256 dari body saja. Webhook developer, yang dijelaskan di sini, mencakup lebih banyak event dan menggunakan tanda tangan v1= dengan timestamp. Lihat Memilih apa yang dikirim.

Endpoint saya mengembalikan 2xx tetapi kode saya tidak melihat apa pun. Periksa apakah eventnya dicentang untuk endpoint tersebut, apakah endpoint tersebut aktif, dan apakah firewall Anda mengizinkan permintaan dari internet.

Mengapa pemeriksaan tanda tangan gagal? Paling sering karena body sudah di-parsing dan di-encode ulang sebelum di-hash. Hash byte mentahnya persis seperti yang diterima.