Webhooks / Callbacks
Receive asynchronous updates when your order completes.
Instead of polling the order-status endpoint, we strongly recommend providing a Callback URL in your Reseller Settings.
When an order reaches a terminal state (success or failed), our background worker will send an HTTP POST request to your callback URL.
The callback URL must be an https:// address on the public internet, at most 2048 characters. A host that resolves to a private, loopback or link-local address is refused, and so is a redirect to one. Redirects to public https:// hosts are followed (up to 5): 307 and 308 re-send the same POST, while 301, 302 and 303 follow as a GET without the body, so point the URL at the final address.
Payload Format
We will send a JSON payload to your server:
{
"ref_id": "R-12345",
"status": "success",
"product_code": "MLBBPH-86",
"product_name": "Mobile Legends 86 Diamonds",
"price": 25000,
"serial_number": "ALG-A1B2C3D4EF",
"message": "Order completed",
"failure_code": null,
"failure_reason": null,
"quantity": 1,
"units": [],
"refunded_amount": null
}Failed Order Payload
A failed order now carries the reason. status and message are unchanged; failure_code and failure_reason were added beside them, so existing integrations keep working untouched.
{
"ref_id": "R-12346",
"status": "failed",
"product_code": "MLBBPH-86",
"product_name": "Mobile Legends 86 Diamonds",
"price": 25000,
"serial_number": null,
"message": "Order failed",
"failure_code": "PRODUCT_UNAVAILABLE",
"failure_reason": "The order was rejected: product not found",
"quantity": 1,
"units": [],
"refunded_amount": 25000
}Both fields can be null on a failure
Some upstream failures reach us as a bare “failed” with no explanation. We send null rather than inventing a reason. failure_code is an open set; handle the codes you know and display failure_reason for the rest. The full list is on the Order Status page.
Combo Orders
A combo product delivers several items under one order (see Order Status).
Its callback fires once per order, when the last item settles, never once per item. The
three fields below were added after every existing key; for an ordinary product they are always
quantity: 1 and units: [].
quantity: number of items (1 for an ordinary product).units: each item withunit_no,product_code,product_name,status,serial_number(success only) andrefund_amount(failed items only, once the order has finished and the refund was credited).refunded_amount: money returned to your balance for this order, on every product: the whole price on a refunded failure, the failed share on a partly delivered combo or bundle.nullwhen nothing was refunded. It always matches GET /order-status.
A partly delivered combo arrives as status: "success" with the unchanged message "Order completed",
failure_code: null, refunded_amount greater than 0 and at least one failed unit. The failed
items’ share has already been credited to your balance.
{
"ref_id": "R-20001",
"status": "success",
"product_code": "ALGAN-MLBB-COMBO-849",
"product_name": "Mobile Legends 849 Diamonds (combo)",
"price": 210000,
"serial_number": "ALG-K2M4P6R8T1, ALG-Q3W5E7R9T2",
"message": "Order completed",
"failure_code": null,
"failure_reason": null,
"quantity": 3,
"units": [
{ "unit_no": 1, "product_code": "ALGAN-MLBB-570", "product_name": "Mobile Legends 570 Diamonds", "status": "success", "serial_number": "ALG-K2M4P6R8T1", "refund_amount": null },
{ "unit_no": 2, "product_code": "ALGAN-MLBB-223", "product_name": "Mobile Legends 223 Diamonds", "status": "success", "serial_number": "ALG-Q3W5E7R9T2", "refund_amount": null },
{ "unit_no": 3, "product_code": "ALGAN-MLBB-56", "product_name": "Mobile Legends 56 Diamonds", "status": "failed", "serial_number": null, "refund_amount": 14000 }
],
"refunded_amount": 14000
}order_code: removed (changelog, 2026-10)
Callbacks no longer carry order_code (AGN- + 12 characters). Every other key keeps its exact
name, type, value and position: ref_id, status, product_code, product_name, price,
serial_number and message are unchanged. Match callbacks on ref_id as you always have.
Signature note
Every new field is inside the signed JSON body, so your existing HMAC verification covers them with no change. Just make sure your parser does not reject unknown keys.
Serial Number Format
The serial_number is always prefixed with ALG-. For voucher products the real redeemable code is appended after a /:
{
"ref_id": "R-99001",
"status": "success",
"product_code": "ALGAN-STEAMPHP-500",
"product_name": "Steam Voucher PHP 500",
"price": 135000,
"serial_number": "ALG-A1B2C3D4EF/STEAMPH-9XQ2-K7MP-44TZ",
"message": "Order completed",
"failure_code": null,
"failure_reason": null,
"quantity": 1,
"units": [],
"refunded_amount": null
}Delivering voucher codes
Split serial_number on the first /: serialNumber.slice(serialNumber.indexOf('/') + 1). Everything after it is the code your customer redeems (e.g. STEAMPH-9XQ2-K7MP-44TZ). Keep that remainder whole: some vouchers are two-part credentials with their own / (a PIN and a password, a serial and a PIN), and your customer needs both parts. A combo’s serial_number joins one serial per delivered item with , ; read each item’s own serial_number in units instead. For instant/direct products there is no /; the value is our reference only, since the top-up is delivered straight to the target account.
Security
To ensure the webhook is genuinely from Algan, we send an X-Signature and an X-Timestamp header. The signature is the same HMAC-SHA256 you use for your requests: HMAC-SHA256(rawBody + timestamp, apiSecret) as lowercase hex. Calls come from our IP address 208.77.246.15; you can whitelist it too.
Verification Steps
- Read the body as raw bytes, before any JSON parsing. A parsed and re-serialised body gives a different signature.
- Check that
X-Timestampis within 5 minutes of your server’s current time. - Compute
HMAC-SHA256(rawBody + timestamp)with yourAPI Secretand compare it withX-Signaturein constant time (for examplecrypto.timingSafeEqualin Node.js,hash_equalsin PHP,hmac.compare_digestin Python). Refuse the call when they differ. - Answer
2xxquickly and do the work after, so the call does not time out (5 seconds). - Be idempotent on
ref_id: a retry, or a resend from your dashboard or our support team, delivers the same callback again.
Test callbacks (changelog, 2026-10-31)
A test order sends one callback with the same shape and the same signature, plus "test": true after every other key. It is sent once and never retried. A simulated failure keeps "message": "Order failed" and carries "failure_code": "TEST_FAILURE". No real callback ever carries test.
Retry Policy
If your server does not answer with a 2xx HTTP status code, or times out after 5 seconds, we retry the callback automatically. The times below are measured from the first attempt, because the waits run back to back:
Retry Schedule
| Parameter | Required | Description |
|---|---|---|
Attempt 1 | No | Immediate: sent right after the order reaches a terminal state (T+0s). |
Attempt 2 | No | 5 seconds after the first attempt (T+5s). |
Attempt 3 | No | 15 seconds after the first attempt (T+15s), a 10 second wait after attempt 2. |
Attempt 4 (Final) | No | 30 seconds after the first attempt (T+30s), a 15 second wait after attempt 3. |
Sizing your reconciliation window
Worst case, the last attempt is fired at T+30s and can still be in flight for its own 5 second timeout, so allow at least 35 seconds from the terminal state before you treat a callback as missing. If your endpoint is slow to answer, every attempt shifts later by however long it holds the connection open.
Permanently Failed
If all 4 attempts fail, the callback is marked as permanently failed. Our worker will not retry again automatically.
You have two options:
- Resend from Dashboard: Go to your Reseller Dashboard → Orders → click the failed order → “Resend Callback”.
- Poll manually: Use the
GET /api/v1/order-status?ref_id=...endpoint to fetch the current order status.