Balance Webhook Configuration

Most resellers use the Dashboard to manage Balance webhooks. These endpoints exist for automation and administrative integrations.

Authentication

These endpoints use the same API-key HMAC authentication as other /v2 endpoints. Include X-Api-Key, X-Timestamp, X-Nonce, and X-Signature; see API Key Authentication for signing instructions. Authentication headers are omitted from the examples below for brevity.

Base URL: https://api.iimmpact.com

Configuration Endpoints

Method	Endpoint	Description
GET	/v2/balance-webhook	Get the current configuration
PUT	/v2/balance-webhook	Create or update the webhook URL
PATCH	/v2/balance-webhook/enabled	Enable or disable delivery
POST	/v2/balance-webhook/rotate-secret	Rotate the signing secret
DELETE	/v2/balance-webhook	Remove the configuration

Get Configuration

GET /v2/balance-webhook HTTP/1.1
Host: api.iimmpact.com

{
  "webhook_url": "https://example.com/webhooks/iimmpact-balance",
  "enabled": true,
  "secret_last_four": "a1b2",
  "created_at": "2026-09-08T04:00:00Z",
  "updated_at": "2026-09-08T04:00:00Z"
}

When no webhook is configured, webhook_url and secret_last_four are empty strings, enabled is false, and both timestamps are null.

Create or Update Configuration

The URL must be an absolute HTTPS URL in production and no more than 500 characters. A newly created configuration is enabled automatically. Updating an existing URL preserves its current secret and enabled state.

PUT /v2/balance-webhook HTTP/1.1
Host: api.iimmpact.com
Content-Type: application/json

{"url":"https://example.com/webhooks/iimmpact-balance"}

Response when creating the configuration:

{
  "webhook_url": "https://example.com/webhooks/iimmpact-balance",
  "webhook_secret": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

When updating an existing configuration, the response contains webhook_url only; webhook_secret is omitted.

Enable or Disable Delivery

PATCH /v2/balance-webhook/enabled HTTP/1.1
Host: api.iimmpact.com
Content-Type: application/json

{"enabled":false}

{
  "enabled": false
}

Rotate Secret

POST /v2/balance-webhook/rotate-secret HTTP/1.1
Host: api.iimmpact.com

{
  "webhook_url": "https://example.com/webhooks/iimmpact-balance",
  "webhook_secret": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789"
}

Store Secrets Immediately

webhook_secret is returned only when PUT /v2/balance-webhook creates a configuration and when POST /v2/balance-webhook/rotate-secret rotates it. Store it securely when returned. Rotation invalidates the previous secret immediately.

Delete Configuration

DELETE /v2/balance-webhook HTTP/1.1
Host: api.iimmpact.com

HTTP/1.1 204 No Content

Deletion is idempotent: deleting when no configuration exists still succeeds.

Delivery Logs

Delivery log endpoints let you list completed deliveries, inspect details, and replay failed events. The Dashboard exposes the same functions at Developer › Webhooks › Delivery Logs › Balance.

Method	Endpoint	Description
GET	/v2/balance-webhook/deliveries	List delivery logs
GET	/v2/balance-webhook/deliveries/{jobId}	Get one delivery
POST	/v2/balance-webhook/deliveries/{jobId}/replay	Replay one failed delivery
POST	/v2/balance-webhook/deliveries/replay-bulk	Replay multiple failed deliveries

Delivery responses use the camelCase field names shown below because they are returned directly by the delivery service.

List Deliveries

Optional query parameters are status (all, success, or failed), from, to, search, limit (1–100; default 50), and the cursor returned by the previous page. Search matches the event ID.

GET /v2/balance-webhook/deliveries?status=failed&limit=50&search=mutasi%3A155062341 HTTP/1.1
Host: api.iimmpact.com

{
  "deliveries": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "eventId": "mutasi:155062341",
      "status": "failed",
      "error": "HTTP 500: unavailable",
      "retryCount": 3,
      "retryLimit": 3,
      "createdAt": "2026-09-08T04:01:00.000Z",
      "completedAt": "2026-09-08T04:08:00.000Z",
      "webhookUrl": "https://example.com/webhooks/iimmpact-balance",
      "webhookMethod": "POST",
      "replayCount": 0,
      "originalJobId": null,
      "payload": {
        "type": "balance.added",
        "version": "1",
        "id": "mutasi:155062341",
        "created_at": "2026-09-07T12:20:00.000Z",
        "data": {
          "resellerCode": "3000001",
          "amount": 1000,
          "balance": 12500.45,
          "description": "MBB TRF 1234"
        }
      },
      "webhookPayload": {
        "type": "balance.added",
        "version": "1",
        "id": "mutasi:155062341",
        "created_at": "2026-09-07T12:20:00.000Z",
        "data": {
          "resellerCode": "3000001",
          "amount": 1000,
          "balance": 12500.45,
          "description": "MBB TRF 1234"
        }
      },
      "responseCode": 500,
      "responseStatusCode": 500,
      "responseBody": "unavailable"
    }
  ],
  "cursor": "11111111-1111-4111-8111-111111111111",
  "hasMore": false
}

Get a Delivery

GET /v2/balance-webhook/deliveries/11111111-1111-4111-8111-111111111111 HTTP/1.1
Host: api.iimmpact.com

{
  "id": "11111111-1111-4111-8111-111111111111",
  "eventId": "mutasi:155062341",
  "status": "failed",
  "error": "HTTP 500: unavailable",
  "retryCount": 3,
  "retryLimit": 3,
  "createdAt": "2026-09-08T04:01:00.000Z",
  "completedAt": "2026-09-08T04:08:00.000Z",
  "webhookUrl": "https://example.com/webhooks/iimmpact-balance",
  "webhookMethod": "POST",
  "replayCount": 0,
  "originalJobId": null,
  "payload": {
    "type": "balance.added",
    "version": "1",
    "id": "mutasi:155062341",
    "created_at": "2026-09-07T12:20:00.000Z",
    "data": {
      "resellerCode": "3000001",
      "amount": 1000,
      "balance": 12500.45,
      "description": "MBB TRF 1234"
    }
  },
  "webhookPayload": {
    "type": "balance.added",
    "version": "1",
    "id": "mutasi:155062341",
    "created_at": "2026-09-07T12:20:00.000Z",
    "data": {
      "resellerCode": "3000001",
      "amount": 1000,
      "balance": 12500.45,
      "description": "MBB TRF 1234"
    }
  },
  "responseCode": 500,
  "responseStatusCode": 500,
  "responseBody": "unavailable"
}

Replay One Delivery

Only failed deliveries can be replayed.

POST /v2/balance-webhook/deliveries/11111111-1111-4111-8111-111111111111/replay HTTP/1.1
Host: api.iimmpact.com

{
  "jobId": "22222222-2222-4222-8222-222222222222",
  "originalJobId": "11111111-1111-4111-8111-111111111111",
  "eventId": "mutasi:155062341"
}

Replay Multiple Deliveries

Submit 1–50 delivery job IDs. Each item reports its own result.

POST /v2/balance-webhook/deliveries/replay-bulk HTTP/1.1
Host: api.iimmpact.com
Content-Type: application/json

{"job_ids":["11111111-1111-4111-8111-111111111111"]}

{
  "results": [
    {
      "jobId": "11111111-1111-4111-8111-111111111111",
      "success": true,
      "newJobId": "22222222-2222-4222-8222-222222222222"
    }
  ]
}

Each event can be replayed manually no more than three times, whether replayed individually, in bulk, or through the Dashboard. A fourth request returns 429 Too Many Requests for a single replay or an item-level error in a bulk replay.

For payload verification, automatic retry behavior, and idempotency, see Balance Webhook Events.