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:

200Webhook Payload
json
{
"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.

200Failed Webhook Payload
json
{
"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 with unit_no, product_code, product_name, status, serial_number (success only) and refund_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. null when 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.

200Combo Webhook Payload (partly delivered)
json
{
"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 /:

200Voucher Webhook Payload
json
{
"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

  1. Read the body as raw bytes, before any JSON parsing. A parsed and re-serialised body gives a different signature.
  2. Check that X-Timestamp is within 5 minutes of your server’s current time.
  3. Compute HMAC-SHA256(rawBody + timestamp) with your API Secret and compare it with X-Signature in constant time (for example crypto.timingSafeEqual in Node.js, hash_equals in PHP, hmac.compare_digest in Python). Refuse the call when they differ.
  4. Answer 2xx quickly and do the work after, so the call does not time out (5 seconds).
  5. 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

ParameterRequiredDescription
Attempt 1NoImmediate: sent right after the order reaches a terminal state (T+0s).
Attempt 2No5 seconds after the first attempt (T+5s).
Attempt 3No15 seconds after the first attempt (T+15s), a 10 second wait after attempt 2.
Attempt 4 (Final)No30 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:

  1. Resend from Dashboard: Go to your Reseller Dashboard → Orders → click the failed order → “Resend Callback”.
  2. Poll manually: Use the GET /api/v1/order-status?ref_id=... endpoint to fetch the current order status.
PreviousValidate IDNextRate Limits