Balance Webhooks

Balance webhooks send a signed balance.added event when an eligible credit is recorded in your IIMMPACT balance, letting your system resume work, reconcile funds, or alert operators without repeatedly checking the Balance API.

Why Use It

Example: Resume Queued Orders After a Top-Up

1. An order fails because your IIMMPACT balance is insufficient.
2. Your system parks the order in a waiting for funds queue.
3. You top up your IIMMPACT balance.
4. Typically within a minute or two of the funds being recorded, your endpoint receives a balance.added event.
5. Your system verifies the signature, reads data.balance, and releases the queued orders that the new balance can cover.

You can also use Balance webhooks for ledger reconciliation, using id as the idempotency key.

For operations alerting, forward accepted events to Slack or Microsoft Teams.

Setup

Configure Balance webhooks from the IIMMPACT Dashboard:

1. Go to Developer › Webhooks › Balance Webhook.
2. Enter your HTTPS webhook URL.
3. Click Register Webhook — your webhook secret is shown once. Store it securely.
4. Share the secret securely with the team implementing signature verification.
5. Use the enable toggle to pause or resume delivery when needed.

DANGER

The webhook secret is shown only when the configuration is created or the secret is rotated. Rotating the secret invalidates the old secret immediately, so update your endpoint at the same time.

From the same section, you can update the URL, enable or disable delivery, rotate the secret, or remove the configuration.

Events While Disabled

Deliveries skipped while the Balance webhook is disabled are not queued for automatic delivery when you re-enable it. Reconcile your ledger for the disabled period before resuming event-driven processing.

What Triggers It

Balance webhooks are sent for positive balance credits that are not linked to a transaction, including:

• Bank transfers
• JomPAY balance deposits
• Manual top-ups performed by IIMMPACT

They are not sent for:

• Refunds
• Commissions
• Balance transfers

Events already more than 48 hours old when detected are considered stale and are not delivered.

How It Works

The balance watcher runs every minute and dispatches new events immediately. Delivery is typically within a minute or two of the funds being recorded in your IIMMPACT balance; bank-transfer detection itself can add a few minutes.

Each eligible credit produces one event with a stable id in the format mutasi:<code>. Delivery is at least once: retries, recovery, or a manual replay can deliver the same event more than once. Store and deduplicate by id before taking action.

Retry Policy

Your endpoint has 10 seconds to respond. Any 2xx response succeeds. Network errors, timeouts, 408, 429, and 5xx responses are retried three times with exponential backoff starting at about 60 seconds. Other 4xx responses are terminal failures.

After retryable failures exhaust the first retry cycle, IIMMPACT continues recovery attempts for up to several hours. See Balance Webhook Events for exact behavior and manual replay rules.

What's Next

• Balance Webhook Events — Payload, headers, signature verification, retries, and handler examples
• Balance Webhook Configuration — Automate configuration and inspect or replay deliveries through the API
• Webhooks Overview — Compare all IIMMPACT webhook types