Daftarkan webhook

Melanggankan URL publik ke event yang didukung. Setiap endpoint menerima secret HMAC-SHA256 sendiri, ditampilkan sekali saat dibuat. Jika hilang, hapus endpoint lalu tambahkan kembali.

POSThttps://notpanel.com/api/v3action=webhook.add

API key diperlukanDibatasi rate (akun bersama + IP + action)Body: application/x-www-form-urlencoded

Maksimum 5 webhook per API key. Gunakan URL HTTPS yang dapat dijangkau publik. Tujuan yang tidak aman, privat, loopback, atau tidak publik ditolak.

Parameter

Nama	Tipe	Deskripsi
keyWajib	string	API key Anda.
actionWajib	string	Harus berupa string literal "webhook.add".
urlWajib	string (URL)	Endpoint HTTPS publik yang akan menerima POST. Harus dapat dijangkau dari internet publik.
events	string (CSV)	Subset dipisah koma dari enam event yang didukung di bawah. Hilangkan untuk melanggan keenamnya.

Contoh request

Ganti YOUR_API_KEY dengan key yang dibuat di halaman API dashboard Anda.

cURLJavaScriptPythonPHP

curl -X POST https://notpanel.com/api/v3 \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "key=YOUR_API_KEY&action=webhook.add&url=https://your-server.example.com/notpanel-webhook&events=order.completed,order.refunded"

const res = await fetch("https://notpanel.com/api/v3", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    key: "YOUR_API_KEY",
    action: "webhook.add",
    url: "https://your-server.example.com/notpanel-webhook",
    events: "order.completed,order.refunded",
  }),
});

const data = await res.json();
console.log(data);

import requests

res = requests.post(
  "https://notpanel.com/api/v3",
  data={
    "key": "YOUR_API_KEY",
    "action": "webhook.add",
    "url": "https://your-server.example.com/notpanel-webhook",
    "events": "order.completed,order.refunded",
},
)
print(res.json())

<?php
$body = http_build_query([
    'key' => 'YOUR_API_KEY',
    'action' => 'webhook.add',
    'url' => 'https://your-server.example.com/notpanel-webhook',
    'events' => 'order.completed,order.refunded',
]);

$response = file_get_contents('https://notpanel.com/api/v3', false, stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/x-www-form-urlencoded\r\n",
        'content' => $body,
        'ignore_errors' => true,
    ],
]));

print_r(json_decode($response, true));

Contoh response

{
  "webhook_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "url": "https://your-server.example.com/notpanel-webhook",
  "secret": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  "events": [
    "order.completed",
    "order.refunded"
  ]
}

Error umum

Status	Body	Penyebab
400	{"error":"Maximum 5 webhook endpoints per API key"}	Endpoint yang ada telah menghabiskan batas. Hapus endpoint yang tidak terpakai dengan action=webhook.remove terlebih dahulu.
400	{"error":"Webhook URL must be a publicly reachable HTTPS URL"}	URL bukan alamat HTTPS yang valid, tidak dapat di-parse, atau me-resolve ke IP privat/loopback.
400	{"error":"Webhook event is invalid","error_code":"INVALID_WEBHOOK_EVENT"}	Nama event tidak ada di allow-list. Periksa kembali ejaan — nama menggunakan bentuk "order.<status>".

Event yang tersedia

order.completed
order.partial
order.processing
order.in_progress
order.refunded
order.refill_completed

Daftar webhook

action=webhook.list mengembalikan setiap endpoint yang terdaftar di bawah key pemanggil, termasuk kesehatan pengirimannya (status, failureCount, lastDeliveredAt).

key=YOUR_API_KEY&action=webhook.list

[
  {
    "id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
    "url": "https://your-server.example.com/notpanel-webhook",
    "events": ["order.completed", "order.refunded"],
    "status": "active",
    "failureCount": 0,
    "lastDeliveredAt": "2026-04-30T15:42:11.000Z",
    "createdAt": "2026-04-15T09:01:00.000Z"
  }
]

Hapus sebuah webhook

action=webhook.remove dengan UUID endpoint menghapus endpoint dan mencabut signing secret-nya. Pengiriman yang sudah berjalan mungkin masih tiba; event baru tidak akan diantrekan untuknya.

key=YOUR_API_KEY&action=webhook.remove&id=3f2504e0-4f89-41d3-9a0c-0305e82c3301

{
  "success": true
}

Payload pengiriman

Setiap pengiriman adalah POST dengan Content-Type: application/json. Body memiliki field top-level events, timestamp, dan deliveryId. Default batching publik saat ini mengelompokkan hingga 5 detik dan memuat maksimum 50 objek event, masing-masing dengan id logis stabil serta event, timestamp, dan data. Antrean atau gangguan dapat menambah jeda, jadi ini bukan janji pengiriman 5 detik. Header meliputi:

X-Webhook-Signature — sha256=<hex>, dihitung atas <timestamp>.<exact JSON body bytes>.
X-Webhook-Timestamp — timestamp Unix pengiriman dalam detik.
X-Webhook-Delivery-Id — UUID batch pengiriman, digunakan ulang ketika batch yang sama dicoba lagi. Tidak ada header event tingkat pengiriman; baca setiap event dari body.

{
  "events": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "event": "order.completed",
      "timestamp": 1777534931,
      "data": {
        "order": 7001,
        "orderId": 7001,
        "serviceId": 1,
        "status": "Completed",
        "status_key": "completed",
        "charge": "0.50",
        "startCount": 1234,
        "remains": 0
      }
    }
  ],
  "timestamp": 1777534931,
  "deliveryId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

Memverifikasi tanda tangan

Baca X-Webhook-Timestamp dan byte body JSON persis seperti diterima. Hitung HMAC-SHA256 atas <timestamp>.<body bytes> dengan secret endpoint, format sebagai sha256=<hex>, lalu bandingkan dengan X-Webhook-Signature secara constant-time. Retry mempertahankan ID event dan deliveryId, tetapi menerima timestamp, body, dan signature baru.

Sebagai kebijakan replay Anda sendiri, Anda dapat menolak pengiriman yang ditandatangani dengan benar jika timestamp-nya berbeda lebih dari 5 menit dari jam server.

Perilaku pengiriman & retry

Best-effort dengan retry. Response 2xx menyelesaikan pengiriman. Setiap percobaan timeout setelah 30 detik. Kegagalan dapat dicoba ulang mulai setelah 5 detik dengan exponential backoff yang dibatasi 5 menit, tetapi pengiriman bukan jaminan at-least-once yang durable.
Ambang jeda. Endpoint dijeda setelah 10 percobaan gagal berturut-turut. Tidak ada action enable atau update; hapus endpoint, lalu daftarkan pengganti dengan action=webhook.add dan simpan secret baru yang ditampilkan.
Urutan tidak dijamin. Buat handler idempotent, proses setiap event dalam batch, deduplikasi transisi logis dengan id event atau batch retry dengan deliveryId, dan rekonsiliasi state penting melalui action=status.