CHAINHULK Developers
Website Workspace
Dokumentasi/Webhooks & pengiriman

Webhooks & pengiriman

Terima event workspace bertanda tangan, periksa riwayat dan kelola retry secara aman.

Buat tujuan webhook

Buka menu Webhooks pada workspace. Pemilik dan admin workspace dapat mengelola integrasi. API key memerlukan webhooks:read untuk membaca konfigurasi dan riwayat, serta webhooks:write untuk membuat, mengubah, menguji, merotasi secret atau mengulang pengiriman. Sesi control-plane maupun izin bantuan staf tidak memberikan akses ke integrasi pelanggan.

POST /api/v1/workspaces/WORKSPACE_ID/webhooks
Authorization: Bearer YOUR_API_KEY
Idempotency-Key: 6881f056-e2d0-4daa-8e2f-3a2879d86a07
Content-Type: application/json

{
  "name": "Layanan pelanggan",
  "url": "https://layanan-anda.com/chainhulk",
  "events": [
    "message.created",
    "message.updated",
    "conversation.updated"
  ],
  "enabled": false
}

URL harus menggunakan HTTPS pada port 443, tanpa userinfo, query atau fragment. Gunakan hostname ASCII atau alamat IP publik. Alamat lokal, privat dan jaringan khusus ditolak. Seluruh jawaban DNS diperiksa pada setiap percobaan, koneksi memakai IP yang telah diperiksa, TLS tetap memverifikasi hostname, dan pengalihan URL tidak diikuti. Maksimal sepuluh tujuan yang belum diarsipkan per workspace.

Respons pembuatan baru mengembalikan 201 dengan webhook dan signing_secret. Simpan signing_secret sebelum meninggalkan halaman. Pengulangan identik dengan Idempotency-Key yang sama mengembalikan 200 dan ID awal tanpa menampilkan secret kembali. Isi berbeda dengan key yang sama menghasilkan 409. URL lengkap dan secret disimpan terenkripsi; respons baca hanya memuat origin tujuan dan metadata.

Event dan payload

  • message.created — pesan masuk yang telah dinormalisasi atau pesan keluar yang masuk antrean. Event ini belum membuktikan pesan telah terkirim ke messenger.
  • message.updated — perubahan pesan, receipt, pembatalan atau ketersediaan lampiran.
  • conversation.updated — perubahan status, penugasan atau pengambilalihan percakapan.
  • webhook.test — event sintetis yang diminta melalui tombol Kirim event uji atau POST /webhooks/{id}/test. Event uji tidak mengirim pesan messenger.
{
  "id": "evt_125",
  "type": "message.updated",
  "timestamp": "2026-11-17T22:00:00Z",
  "workspace_id": 12,
  "data": {
    "resource_id": "0c2ba285-b306-4549-adcc-c142d0914175",
    "message_id": "0c2ba285-b306-4549-adcc-c142d0914175",
    "status": "sent"
  }
}

Payload hanya membawa ID sumber dan metadata perubahan yang tersedia. Field status dan ID terkait bersifat opsional. Teks pesan, nomor pelanggan, isi lampiran, URL objek dan secret tidak disertakan. Gunakan resource_id serta API REST dengan scope yang sesuai untuk membaca detail terbaru. Event id tetap mengidentifikasi event sumber; webhook-id mengidentifikasi pengiriman ke satu tujuan.

Verifikasi tanda tangan

Permintaan POST menggunakan pola HMAC-SHA256 Standard Webhooks v1. Header Webhook-Id adalah UUID pengiriman yang tetap sama pada retry. Webhook-Timestamp adalah waktu percobaan dalam Unix detik. Webhook-Signature berisi v1, diikuti HMAC dalam Base64. Hapus prefix whsec_ dari signing secret dan dekode Base64 untuk memperoleh kunci 32 byte. Data yang ditandatangani adalah webhook-id + titik + webhook-timestamp + titik + body mentah yang diterima.

import {createHmac, timingSafeEqual} from "node:crypto";

export function verifyWebhook(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signature = headers["webhook-signature"];
  if (typeof id !== "string" || !/^[0-9a-f-]{36}$/.test(id) ||
      typeof timestamp !== "string" || !/^\d{1,12}$/.test(timestamp) ||
      typeof signature !== "string") return false;
  const seconds = Number(timestamp);
  if (Math.abs(Date.now() / 1000 - seconds) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.`).update(rawBody).digest();
  return signature.split(" ").some(part => {
    if (!part.startsWith("v1,")) return false;
    const received = Buffer.from(part.slice(3), "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

Verifikasi body mentah sebelum parsing JSON. Jangan serialisasi ulang body sebelum memeriksa HMAC. Tolak timestamp di luar toleransi lima menit dan pastikan jam server tersinkronisasi. Simpan Webhook-Id secara unik bersama hasil pemrosesan agar pengiriman berulang tidak menjalankan tindakan dua kali. Simpan event secara permanen sebelum mengembalikan 2xx; proses lanjutan dapat berjalan melalui antrean aplikasi penerima.

Retry dan riwayat pengiriman

Pengiriman bersifat at least once dan tidak menjamin urutan. Timeout, gangguan DNS/koneksi, HTTP 408, 425, 429 dan 5xx dapat dicoba kembali. HTTP 2xx menandakan diterima; 3xx dan 4xx lainnya menghentikan siklus otomatis. Setiap siklus memiliki maksimal delapan percobaan. Jeda berturut-turut sekitar 5 detik, 30 detik, 5 menit, 30 menit, 2 jam, 6 jam dan 16 jam, dengan jitter. Retry-After diperhitungkan sampai satu jam. Batas satu permintaan adalah sepuluh detik.

  • GET /webhooks/{id}/deliveries menampilkan 50 pengiriman dengan next_cursor. Kirim cursor untuk halaman berikutnya.
  • GET /webhook-deliveries/{id} memuat payload aman dan maksimal 100 percobaan terbaru. Respons hanya menyimpan kode HTTP dan kode error tersanitasi; body respons tujuan tidak disimpan.
  • POST /webhook-deliveries/{id}/retry memulai siklus baru untuk pengiriman failed yang masih sesuai konfigurasi aktif. ID dan body tetap sama; seluruh riwayat tetap disimpan.
  • POST /webhooks/{id}/test memerlukan Idempotency-Key. Pengujian dapat dilakukan pada tujuan nonaktif, selama belum diarsipkan.

Perubahan, rotasi dan arsip

PATCH /webhooks/{id}, DELETE /webhooks/{id} dan POST /webhooks/{id}/rotate-secret memerlukan version konfigurasi saat ini pada body JSON. Versi lama menghasilkan 409. PATCH mengirim name, events, enabled, version, serta url jika ingin mengganti tujuan. URL kosong mempertahankan tujuan sebelumnya. Perubahan konfigurasi membatalkan pengiriman lama yang masih menunggu, termasuk event uji. Permintaan yang sudah berjalan diselesaikan sebelum respons perubahan dikembalikan.

Rotasi membuat signing_secret baru yang hanya ditampilkan pada respons mutasi tersebut. Perbarui aplikasi penerima sebelum mengaktifkan alur baru. Pengiriman lama yang telah gagal tidak dapat diulang dengan konfigurasi versi berbeda. Arsip menghentikan event baru dan mempertahankan riwayat. Endpoint baru menerima event setelah dibuat; riwayat sebelum pembuatan tidak dikirim otomatis.

Referensi: https://www.standardwebhooks.com/ dan spesifikasi Standard Webhooks v1.0.0 di https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md .