Dashboard Utama

Webhooks

Webhooks memungkinkan Anda untuk menerima pemberitahuan HTTP callback secara real-time langsung ke server Anda ketika terjadi aktivitas tertentu pada akun WhatsApp Anda.

Anda dapat mendaftarkan endpoint callback publik Anda di tab Webhooks pada Portal Developer.

Kategori Event Utama

BaBlast menyederhanakan jenis event callback menjadi 2 kategori utama:

1. Pesan Masuk (incoming_message)

Callback akan dikirimkan setiap kali ada chat, teks, atau media masuk dari pelanggan ke nomor WhatsApp Anda.

2. Status Delivery (message_status)

Callback akan dikirimkan secara otomatis untuk memantau status siklus pengiriman notifikasi/pesan Anda yang meliputi sub-event:

  • message_sent (Terkirim dari antrean BaBlast)
  • message_delivered (Diterima oleh HP tujuan)
  • message_read (Dibaca oleh penerima)
  • message_failed (Gagal dikirimkan)

Contoh Payload Webhook (incoming_message)

Ketika ada pesan masuk, server BaBlast akan mengirimkan request POST berisi JSON payload berikut ke URL webhook Anda:

hljs json
{
  "event": "incoming_message",
  "timestamp": "2026-08-12T10:30:00.000Z",
  "sender_id": "12",
  "data": {
    "message_id": "msg_9876543210",
    "from": "[email protected]",
    "from_phone": "6281234567890",
    "from_name": "Customer Demo",
    "to": "6289876543210",
    "message_type": "text",
    "content": "Halo! Saya ingin bertanya mengenai layanan integrasi.",
    "media_url": null,
    "timestamp": "2026-08-12T10:30:00.000Z",
    "channel": "unofficial"
  }
}

Contoh Payload Webhook (message_status)

Ketika status pengiriman pesan berubah, server BaBlast akan mengirimkan request POST ke URL webhook Anda. Jika Anda memilih event message_status, webhook akan mencakup sub-event status seperti message_sent, message_delivered, message_read, atau message_failed.

Contoh payload untuk pesan Standard WA (Unofficial) yang sudah diterima oleh HP tujuan:

hljs json
{
  "event": "message_delivered",
  "timestamp": "2026-08-12T10:31:15.000Z",
  "sender_id": "12",
  "blast_id": "99",
  "data": {
    "message_id": "wa_1234567890",
    "blast_id": "99",
    "recipient": "6281234567890",
    "status": "terkirim",
    "timestamp": "2026-08-12T10:31:15.000Z",
    "channel": "unofficial",
    "error": null
  }
}

Contoh payload untuk pesan WABA yang sudah dibaca:

hljs json
{
  "event": "message_read",
  "timestamp": "2026-08-12T10:32:00.000Z",
  "sender_id": "18",
  "data": {
    "message_id": "wamid.HBgMNjI4MTIzNDU2Nzg5MBUCABEYEj...",
    "recipient_id": "6281234567890",
    "status": "dibaca",
    "timestamp": "2026-08-12T10:32:00.000Z",
    "channel": "waba",
    "error": null,
    "metadata": {
      "conversation_id": "conv_abc123",
      "pricing_category": "utility"
    }
  }
}

Untuk status gagal, field error dapat berisi detail penyebab kegagalan dari WhatsApp atau BaBlast.

Verifikasi Signature (Keamanan)

Untuk memastikan bahwa payload webhook benar-benar dikirim oleh BaBlast (dan tidak dimanipulasi oleh pihak ketiga), disarankan untuk memverifikasi signature.

Setiap request callback dari BaBlast menyertakan header keamanan berikut apabila Secret Token diisi di konfigurasi webhook Anda:

  • X-Webhook-Event: Jenis event (misal incoming_message).
  • X-Webhook-Timestamp: Waktu request dikirim.
  • X-Webhook-Signature: Tanda tangan keamanan berupa hash HMAC-SHA256 dari seluruh string payload body JSON dengan kunci Secret Token Anda.

Contoh Kode Verifikasi (Node.js)

hljs javascript
const crypto = require("crypto");

function verifyWebhook(req, secretToken) {
  const signature = req.get("X-Webhook-Signature") || "";
  const rawBody = JSON.stringify(req.body);
  
  const expectedSignature = "sha256=" + crypto
    .createHmac("sha256", secretToken)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Contoh Kode Verifikasi (PHP)

hljs php
<?php
$secretToken = 'YOUR_SECRET_TOKEN';
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$expectedSignature = 'sha256=' . hash_hmac('sha256', $rawBody, $secretToken);

if (hash_equals($expectedSignature, $signature)) {
    // Request valid dan aman
    http_response_code(200);
    echo "OK";
} else {
    // Request tidak valid / palsu
    http_response_code(401);
    exit("Invalid signature");
}