Webhook

Webhook adalah pemberitahuan satu arah. Setiap kali terjadi sesuatu di akun Anda — pesan masuk, percakapan baru, status berubah — pembalasan.id mengirim data kejadian itu sebagai HTTP POST ke URL yang Anda daftarkan. Sistem Anda menerima, lalu memprosesnya sendiri.

Webhook tidak bisa membalas atau mengubah apa pun di percakapan. Untuk itu, gunakan Agent Bot.

Kapan dipakai

Mencatat percakapan/pesan baru ke Google Sheets, CRM, atau database Anda.
Mengirim notifikasi internal (Slack, Telegram tim) saat pelanggan menghubungi.
Mengalirkan data ke dashboard analitik atau alat otomasi (n8n, Zapier, Make).

Event yang tersedia

Saat membuat webhook, Anda memilih event mana saja yang ingin diterima:

Event	Dikirim ketika
`conversation_created`	Percakapan baru dibuat
`conversation_updated`	Detail percakapan berubah
`conversation_status_changed`	Status berubah (Terbuka, Selesai, Tunda, Snooze)
`message_created`	Ada pesan baru (masuk atau keluar)
`message_updated`	Pesan diperbarui
`contact_created`	Kontak baru dibuat
`contact_updated`	Data kontak berubah
`webwidget_triggered`	Pengunjung membuka live chat di situs Anda
`inbox_created`	Inbox baru dibuat
`inbox_updated`	Pengaturan inbox berubah
`conversation_typing_on` / `conversation_typing_off`	Pelanggan mulai / berhenti mengetik

Cara membuat

Buat webhook lewat API dengan menyertakan url tujuan dan daftar subscriptions (event yang ingin diterima):

curl -X POST 'https://api-c6tw.pembalasan.id/api/v1/accounts/{account_id}/webhooks' \
  -H 'api_access_token: TOKEN_ANDA' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://sistem-anda.com/webhook",
    "subscriptions": ["conversation_created", "message_created"]
  }'

Lihat detail lengkap di referensi API: Add a webhook.

Setiap webhook punya secret yang dipakai untuk menandatangani (sign) tiap kiriman. Verifikasi tanda tangan ini di sisi server Anda untuk memastikan request benar-benar berasal dari pembalasan.id.

Verifikasi tanda tangan (HMAC)

Agar yakin request benar-benar dari pembalasan.id (bukan pihak lain), verifikasi tanda tangan pada setiap kiriman. Setiap POST membawa header berikut:

Header	Isi
`X-Chatwoot-Signature`	`sha256=<hmac>` — tanda tangannya
`X-Chatwoot-Timestamp`	Waktu kirim (unix), ikut ditandatangani
`X-Chatwoot-Delivery`	ID unik pengiriman (untuk mencegah proses ganda)

Tanda tangan dihitung dengan HMAC-SHA256, memakai secret webhook sebagai kunci atas gabungan timestamp + titik + body mentah:

sha256=HMAC_SHA256( secret, timestamp + "." + body_mentah )

secret diambil dari record webhook (field secret pada response API webhook).

Gunakan body mentah persis seperti diterima. Jangan parse JSON lalu susun ulang — perubahan spasi atau urutan kunci akan membuat tanda tangan tidak cocok.

Contoh di Next.js (Route Handler):

import crypto from 'crypto';

export async function POST(req) {
  const rawBody = await req.text(); // mentah, sebelum JSON.parse
  const signature = req.headers.get('x-chatwoot-signature');
  const timestamp = req.headers.get('x-chatwoot-timestamp');

  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(`${timestamp}.${rawBody}`)
      .digest('hex');

  const a = Buffer.from(signature ?? '');
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return new Response('invalid signature', { status: 401 });
  }

  const payload = JSON.parse(rawBody);
  // ...proses event...
  return Response.json({ ok: true });
}

Bandingkan tanda tangan dengan fungsi constant-time (timingSafeEqual, hash_equals), bukan ===, untuk mencegah timing attack. Anda juga bisa menolak request yang timestamp-nya terlalu lama untuk mencegah serangan replay.

Bentuk data yang dikirim

Setiap kiriman berisi nama event dan data terkait. Contoh ringkas untuk message_created:

{
  "event": "message_created",
  "id": 12345,
  "content": "Halo, apakah masih buka?",
  "message_type": "incoming",
  "conversation": { "id": 678, "status": "open" },
  "sender": { "name": "Budi", "email": null }
}

Webhook hanya memberi tahu. Jika Anda butuh sesuatu yang membalas otomatis atau mengubah status percakapan, gunakan Agent Bot.

Kapan dipakai

Event yang tersedia

Cara membuat

Verifikasi tanda tangan (HMAC)

Bentuk data yang dikirim

On this page