Webhooks

Terima notifikasi real-time dari Mutasiku ke endpoint aplikasi Anda.

Webhook dikirim sebagai HTTP POST dari server Mutasiku ke URL endpoint Anda. Daftarkan endpoint di dashboard → Integrasi → Webhooks.


Setup

Buat endpoint di aplikasi Anda

Buat route HTTP yang dapat menerima POST request dari internet.

app.post('/webhook', (req, res) => {
  res.json({ received: true });
});

Daftarkan webhook di dashboard

Buka Integrasi → Webhooks di dashboard, klik Tambah Webhook, dan masukkan URL endpoint Anda. URL harus domain publik dengan http:// atau https:// — localhost dan alamat IP ditolak.

Secara default webhook menerima event dari semua akun Anda. Anda bisa membatasinya ke akun tertentu lewat pilihan Akun pada webhook tersebut.

Pilih events yang ingin diterima

Pilih event spesifik atau subscribe ke semua event.

Implementasikan verifikasi signature

Verifikasi header X-Webhook-Signature di setiap request masuk. Lihat bagian Security di bawah.

Test webhook Anda

Gunakan fitur test di dashboard untuk mengirim event percobaan ke endpoint Anda.


Available Events

Account Events

EventKeterangan
account.createdAkun baru dibuat
account.updatedDetail akun diperbarui

Payload account.created

{
  "type": "account.created",
  "data": {
    "id": "acc_123456789",
    "accountId": "acc_123456789",
    "email": "user@example.com",
    "name": "Test User",
    "createdAt": "2023-05-20T12:34:56.789Z"
  }
}

Payload account.updated

{
  "type": "account.updated",
  "data": {
    "id": "acc_123456789",
    "accountId": "acc_123456789",
    "email": "updated@example.com",
    "name": "Updated User",
    "updatedAt": "2023-05-20T12:34:56.789Z"
  }
}

Mutations Events

EventKeterangan
mutations.createdMutasi/transaksi baru terdeteksi
balance.updatedSaldo akun berubah

Payload mutations.created

{
  "type": "mutations.created",
  "data": {
    "accountId": "acc_123456789",
    "amount": 1000000,
    "type": "CREDIT",
    "description": "Transfer masuk",
    "createdAt": "2023-05-20T12:34:56.789Z"
  }
}

Payload balance.updated

{
  "type": "balance.updated",
  "data": {
    "id": "bal_update_123456789",
    "accountId": "acc_123456789",
    "previousBalance": 5000000,
    "newBalance": 6000000,
    "currency": "IDR",
    "updatedAt": "2023-05-20T12:34:56.789Z"
  }
}

Payment Events

EventKeterangan
payment.createdPembayaran baru dibuat
payment.completedPembayaran berhasil

Pembayaran yang kadaluarsa atau gagal tidak dikirim sebagai webhook. Untuk memastikannya, cek status pembayaran — tagihan yang belum COMPLETED setelah expiresAt berstatus EXPIRED.

Payload payment.created

{
  "type": "payment.created",
  "data": {
    "paymentId": "595a196b-191c-4767-818e-a7646dd048e8",
    "orderId": "order-123",
    "amount": 100000,
    "uniqueCode": 0,
    "status": "PENDING",
    "expiresAt": "2026-11-09T10:32:52.268Z",
    "paymentUrl": "https://mutasiku.co.id/pay/TOKEN"
  }
}

uniqueCode bernilai null bila metodenya belum dipilih pembeli. Untuk pembayaran ke akun sendiri, payload juga berisi ewallet (nama provider, nomor, dan nama akun penerima).

Payload payment.completed

{
  "type": "payment.completed",
  "data": {
    "paymentRequestId": "595a196b-191c-4767-818e-a7646dd048e8",
    "orderId": "order-123",
    "amount": 100123,
    "uniqueCode": 123,
    "description": "Pembelian paket Pro",
    "customerName": "Test Customer",
    "customerEmail": "customer@example.com",
    "customerPhone": "081234567890",
    "status": "COMPLETED",
    "completedAt": "2026-11-09T06:14:03.000Z",
    "transaction": {
      "id": "c1f04b2e-8a3d-4f6e-9b1a-2d7c5e8f0a13",
      "amount": 100123,
      "description": "Transfer masuk",
      "provider": "DANA",
      "providerOrderId": "20261109111212800110166041234567890",
      "transactionDate": "2026-11-09T06:14:03.000Z"
    },
    "metadata": { "productId": "prod_123" }
  }
}

Transaksi Payment Gateway tidak dikirim ke webhook yang Anda buat sendiri. Event-nya dikirim ke webhook Payment Gateway — dibuat otomatis dari URL webhook yang disetujui admin, dan tampil di daftar webhook dengan label Payment Gateway. URL webhook itu tidak bisa diubah langsung; ajukan perubahannya dari dashboard → Payment Gateway → Integrasi.


Security — Verifikasi Signature

Selalu verifikasi X-Webhook-Signature sebelum memproses payload. Abaikan request tanpa signature valid untuk mencegah pemalsuan event.

Signature dibuat menggunakan HMAC-SHA256 dengan secret webhook Anda sebagai key dan field data (JSON string) sebagai message.

signature = HMAC-SHA256(JSON.stringify(payload.data), webhookSecret)

Node.js

const crypto = require('crypto');

function verifySignature(data, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(data))
    .digest('hex');

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

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!verifySignature(req.body.data, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  switch (req.body.type) {
    case 'payment.completed':
      // handle pembayaran berhasil
      break;
    case 'mutations.created':
      // handle mutasi baru
      break;
  }

  res.json({ received: true });
});

PHP

function verifySignature($data, $signature, $secret) {
  $expected = hash_hmac('sha256', json_encode($data), $secret);
  return hash_equals($expected, $signature);
}

$payload   = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!verifySignature($payload['data'], $signature, 'your_webhook_secret')) {
  http_response_code(401);
  echo json_encode(['error' => 'Invalid signature']);
  exit;
}

echo json_encode(['received' => true]);

Python

import json, hmac, hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)

def verify_signature(data, signature, secret):
    expected = hmac.new(
        key=secret.encode(),
        msg=json.dumps(data).encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature', '')
    payload   = request.json

    if not verify_signature(payload['data'], signature, 'your_webhook_secret'):
        return jsonify({'error': 'Invalid signature'}), 401

    return jsonify({'received': True})

Best Practices

Kembalikan 2xx segera. Jangan tunggu proses selesai — kirim respons 200 lebih dulu, lalu proses event secara asinkron dengan queue/job. Jika endpoint tidak merespons dalam 30 detik, Mutasiku akan retry.

Idempotent handler. Event yang sama bisa dikirim lebih dari sekali. Gunakan ID pembayaran dari payload (paymentRequestId pada payment.completed) sebagai idempotency key untuk mencegah proses duplikat.

Simpan raw payload. Log seluruh payload yang masuk untuk keperluan debugging dan audit.


Troubleshooting

MasalahSolusi
Webhook tidak diterimaPastikan URL endpoint dapat diakses dari internet (bukan localhost)
Signature tidak validGunakan JSON.stringify(payload.data), bukan seluruh payload
TimeoutKembalikan 200 segera, proses logic secara asinkron
Event duplikatImplementasikan idempotency key menggunakan ID pembayaran di payload
Transaksi gateway tidak masukEvent Payment Gateway hanya dikirim ke webhook Payment Gateway, bukan webhook buatan Anda

© 2026 PT. Cobra Code Indonesia. All rights reserved.

Last updated: 11/10/2026