API Portal

Webhooks & Real-time Events

Arsitektur B2B Crevir sangat tidak merekomendasikan klien melakukan penarikan data berulang (long polling) secara konstan. Sebaliknya, kami menyediakan sistem Webhooks tangguh yang akan secara proaktif mendorong (push) data seketika (real-time) ke sistem server Anda manakala terjadi perubahan event yang kritikal.

Webhooks sangat esensial untuk melacak status kampanye dan memantau rilis dana Escrow tanpa menabrak batas Rate Limit.

Pendaftaran Webhook

Untuk saat ini, URL Webhook Endpoint (sistem tujuan) harus Anda daftarkan secara manual pada Console > Settings > Developer.

  • Sistem Anda harus mampu merespons panggilan kami dengan HTTP 200 OK dalam kurun waktu 3 detik.
  • Apabila gagal (Timeout atau menerima kode HTTP 4xx/5xx), infrastruktur Crevir akan mencoba ulang (Retry) pengiriman payload dengan jeda eksponensial maksimal hingga 3 kali.

Payload Event Standar

Setiap HTTP POST yang dikirimkan Crevir ke server Anda akan memiliki skema JSON seragam yang dibungkus oleh meta type:

{
  "id": "evt_9bA2z8Xq",
  "type": "campaign.matched",
  "created_at": "2026-07-21T10:05:22Z",
  "data": {
    "campaign_id": "cmp_8z7XbQwe",
    "creator_id": "cre_9x8B2jKl"
  }
}

Daftar Event yang Didukung

Nama EventKeterangan
campaign.matchedAlgoritma (atau konfirmasi manual) telah mengunci kreator ke kampanye Anda.
draft.submittedKreator telah mengunggah pratinjau tautan konten sebelum tayang publik.
escrow.releasedDana kampanye di rekening penampungan telah otomatis dicairkan ke kreator.

Memvalidasi Keamanan Webhook

Mengingat infrastruktur Anda akan terekspos ke publik, sangat berbahaya apabila URL Webhook Anda dieksekusi oleh peretas (Bad Actor) yang berpura-pura menjadi server Crevir.

Untuk mencegah eksploitasi, setiap pengiriman Webhook dari Crevir selalu ditandatangani (Signed) menggunakan kriptografi berbasis HMAC-SHA256.

Tanda tangan ini dilekatkan pada Header HTTP bernama: Crevir-Signature.

Verifikasi Signature (Contoh Node.js)

Gunakan Webhook Secret Key yang diberikan pada Console untuk memverifikasi integritas payload mentah (Raw Body).

const crypto = require('crypto');

function verifyCrevirWebhook(rawBody, signatureHeader, secretKey) {
  // 1. Ekstrak timestamp (t=) dan signature (v1=) dari header
  // Header contoh: "t=1784617489,v1=a1b2c3d4..."
  const elements = signatureHeader.split(',');
  const timestamp = elements[0].split('=')[1];
  const signature = elements[1].split('=')[1];

  // 2. Cegah Replay Attacks (Tolak request yang usianya > 5 menit)
  const currentTimestamp = Math.floor(Date.now() / 1000);
  if (currentTimestamp - timestamp > 300) {
    throw new Error("Webhook Kadaluarsa (Kemungkinan Replay Attack)");
  }

  // 3. Susun data payload yang ditandatangani
  const signedPayload = `${timestamp}.${rawBody}`;

  // 4. Hitung HMAC-SHA256
  const expectedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(signedPayload)
    .digest('hex');

  // 5. Bandingkan dengan aman
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
    throw new Error("Signature Webhook Tidak Valid");
  }

  return true; // Webhook Aman untuk Diproses
}

[!WARNING] Pastikan Anda menggunakan Raw Body Text (buffer asli HTTP) saat melakukan perhitungan hash, bukan hasil JSON yang sudah di-parse (misal: bukan dari req.body jika Anda menggunakan body-parser otomatis di Express). Menggunakan objek yang di-parse akan menyebabkan kegagalan pencocokan hash akibat perubahan whitespace.

← SebelumnyaPengantar API