Webhooks

Panduan setup webhook TransX402 — terima notifikasi pembayaran real-time, verifikasi tanda tangan HMAC-SHA256, dan kebijakan retry.

Ringkasan

Webhook memungkinkan server Anda menerima notifikasi real-time saat pembayaran terjadi. Alih-alih polling API untuk mengecek status pembayaran, TransX402 akan mengirim HTTP POST request ke URL yang Anda tentukan setiap kali ada event pembayaran.

Setup Webhook

1. Konfigurasi URL Webhook

Buka halaman Settings di dashboard TransX402 dan masukkan URL webhook Anda:

https://blogsaya.com/webhook/transx402

Atau via API:

curl -X PATCH https://api.transx402.com/merchant/me \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://blogsaya.com/webhook/transx402",
    "webhookSecret": "auto"
  }'

Saat webhookSecret diset ke "auto", sistem akan men-generate secret secara otomatis. Secret ini digunakan untuk menandatangani payload webhook.

2. Implementasi Endpoint Webhook

Buat endpoint di server Anda yang menerima POST request dari TransX402:

// Express.js
app.post('/webhook/transx402', (req, res) => {
  const payload = req.body;
 
  // Verifikasi tanda tangan (penting!)
  if (!verifySignature(req, payload)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
 
  // Proses event
  switch (payload.event) {
    case 'payment.confirmed':
      handlePaymentConfirmed(payload.data);
      break;
    case 'payment.failed':
      handlePaymentFailed(payload.data);
      break;
  }
 
  // Selalu respons 200 untuk menandakan penerimaan berhasil
  res.status(200).json({ received: true });
});

Payload Webhook

Format

{
  "event": "payment.confirmed",
  "data": {
    "txHash": "0x...",
    "from": "0xPembayar",
    "to": "0xMerchant",
    "token": "IDRX",
    "amount": "150000000000000000000000",
    "amountFormatted": "150000",
    "currency": "IDR",
    "network": "base",
    "resource": "https://example.com/artikel/123",
    "timestamp": "2026-04-01T10:30:00Z"
  },
  "signature": "sha256=..."
}

Tipe Event

Verifikasi Tanda Tangan

Setiap webhook request menyertakan header X-TransX402-Signature yang berisi HMAC-SHA256 dari body request menggunakan webhook secret merchant. Anda harus memverifikasi tanda tangan ini untuk memastikan webhook benar-benar berasal dari TransX402.

Node.js

import crypto from 'crypto';
 
function verifyWebhookSignature(req, webhookSecret) {
  const signature = req.headers['x-transx402-signature'];
  const body = JSON.stringify(req.body);
 
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(body)
    .digest('hex');
 
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Python

import hmac
import hashlib
 
def verify_webhook_signature(body: bytes, signature: str, webhook_secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        webhook_secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
 
    return hmac.compare_digest(signature, expected)

PHP

function verifyWebhookSignature($body, $signature, $webhookSecret) {
    $expected = 'sha256=' . hash_hmac('sha256', $body, $webhookSecret);
    return hash_equals($expected, $signature);
}

Kebijakan Retry

Jika endpoint webhook Anda tidak merespons dengan status 2xx (200-299), TransX402 akan mencoba ulang pengiriman dengan exponential backoff:

Setelah 5 percobaan gagal, webhook dianggap gagal dan tidak akan dicoba lagi. Anda bisa melihat status pengiriman webhook di halaman Settings pada dashboard.

Tips untuk Endpoint Webhook

1. Respons cepat — Kembalikan 200 sesegera mungkin, proses event secara asinkron jika perlu
2. Idempoten — Pastikan endpoint Anda bisa menerima event yang sama lebih dari sekali tanpa efek samping (webhook bisa dikirim ulang)
3. Verifikasi tanda tangan — Selalu verifikasi HMAC-SHA256 signature untuk keamanan
4. Log semua event — Simpan log webhook yang diterima untuk debugging

Testing Webhook

Kirim Test Event

Anda bisa mengirim test event dari halaman Settings di dashboard dengan mengklik tombol "Send Test Event". Ini akan mengirim payload webhook test ke URL webhook Anda.

Gunakan Sandbox

Semua pembayaran di sandbox juga mengirim webhook. Ini memungkinkan Anda menguji seluruh alur webhook tanpa melakukan pembayaran nyata:

1. Set webhook URL di dashboard
2. Lakukan pembayaran sandbox
3. Periksa apakah webhook diterima dengan benar
4. Verifikasi signature validation berfungsi
5. Pastikan logika bisnis Anda memproses event dengan benar

Tool Debugging

Untuk testing dan debugging, Anda bisa menggunakan tool seperti:

• webhook.site — Terima dan inspeksi webhook request secara real-time
• ngrok — Ekspos localhost ke internet untuk menerima webhook selama development

# Contoh menggunakan ngrok
ngrok http 3000
# Gunakan URL ngrok sebagai webhook URL di dashboard
# https://abc123.ngrok.io/webhook/transx402

Status Pengiriman

Di halaman Settings pada dashboard, Anda bisa melihat statistik pengiriman webhook:

• Total — Jumlah total webhook yang dikirim
• Delivered — Jumlah webhook yang berhasil diterima (respons 2xx)
• Failed — Jumlah webhook yang gagal setelah semua retry

Setiap pengiriman webhook dicatat di database untuk audit trail dan debugging.