Webhooks

Quick start

The shortest path from zero to a verified delivery:

Create an endpoint. POST /v0/webhooks with a public URL — save the secret from the response, you’ll need it to verify signatures.
Verify the signature on incoming requests with HMAC-SHA256(secret, raw_body) against the X-Superbank-Signature header (jump to Verifying signatures).
Return 200 quickly, then process asynchronously. Anything 2xx counts; anything else triggers a retry.

The basics

Supported events

Event	When it fires
`account.created`	A new account was provisioned
`account.updated`	Account balance or status changed
`account.deleted`	An account was deactivated
`payment.created`	A new payment was created
`payment.updated`	A payment status changed
`settlement_request.created`	A new settlement request was created
`settlement_request.updated`	A settlement request status changed

Envelope and headers

Every delivery uses the same JSON envelope. Field names are snake_case; the data object varies by event type. The full payload for each event is in Event payload reference at the bottom.

{
  "event": "<event_type>",
  "data": { ... },
  "timestamp": "2026-01-26T15:48:08.700Z"
}

Header	Description
`Content-Type`	`application/json`
`X-Superbank-Signature`	HMAC-SHA256 signature: `sha256=<hex>`
`X-Superbank-Event`	Event type (e.g., `payment.updated`)

Verifying signatures

Compute sha256=HMAC-SHA256(secret, request_body) over the raw request body and compare it to the X-Superbank-Signature header using a constant-time comparison. Verify before parsing — see Common pitfalls.

Node.js
Python

const crypto = require('crypto');

function verifyWebhookSignature(secret, payload, signatureHeader) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  const received = signatureHeader.replace('sha256=', '');
  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(received, 'hex')
  );
}

// Express middleware example — note `express.raw` so the body stays bytes
app.post('/webhooks/superbank', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-superbank-signature'];
  const isValid = verifyWebhookSignature(
    process.env.WEBHOOK_SECRET,
    req.body,
    signature
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Handle event...
  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_webhook_signature(secret: str, payload: bytes, signature_header: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    received = signature_header.replace('sha256=', '')
    return hmac.compare_digest(expected, received)

# Flask example — `request.data` is the raw bytes, not the parsed JSON
@app.route('/webhooks/superbank', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Superbank-Signature')
    is_valid = verify_webhook_signature(
        os.environ['WEBHOOK_SECRET'],
        request.data,
        signature
    )

    if not is_valid:
        return 'Invalid signature', 401

    event = request.get_json()
    # Handle event...
    return 'OK', 200

Reliability

Retry policy

If your endpoint returns a non-2xx response or times out (30 seconds), Superbank retries with exponential backoff:

Attempt	Delay	Cumulative
1	Immediate	—
2	1 minute	1 minute
3	5 minutes	6 minutes
4	15 minutes	21 minutes
5	1 hour	~1.3 hours
6	1 day	~1.3 days
7	2 days	~3.3 days
8	4 days	~7.3 days
9	1 week	~14.3 days
10	2 weeks	~28.3 days

After 10 failed attempts, the delivery is marked as permanently failed.

Common pitfalls

Verify before parse. Run signature verification on the raw bytes before JSON.parse. Frameworks that auto-parse JSON (Express default, NestJS body parser) will silently re-serialize the body and your HMAC will never match — use express.raw / request.data / equivalent to hold onto the original bytes. - Return 200 fast, process async. Heavy work on the request thread blows past the 30-second timeout and triggers retries. Acknowledge, then enqueue. - Expect at-least-once delivery. Retries are real — the same event can land twice. Make handlers idempotent on the event id (or on data.id + status transition). - Don’t filter by source IP. Egress IPs change without notice; rely on the signature.

Testing

Test deliveries

Test deliveries land at your endpoint with two markers your handler should expect:

data.test: true — every test payload sets a top-level test: true inside data. Branch on it if you want to short-circuit business logic for test events.
Sentinel resource IDs — IDs use the prefix 00000000-0000-0000-0000-..., with the last digit identifying the resource type (...001 settlement request, ...002 outbound payment, etc.). Allow-list these prefixes if your handler validates IDs against your database.

Headers and signature are computed exactly as in production, so a handler that verifies signatures accepts test deliveries without any code branch.

From your local machine with ngrok

ngrok creates a public tunnel to your localhost so sandbox deliveries land directly on your dev box.

# 1. Start your handler (whichever port it binds to)
node server.js

# 2. Tunnel it
ngrok http 3000

# 3. Register the public URL it prints
curl --request POST \
  --url https://api-sandbox.superbank.co/v0/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{ "url": "https://abc123.ngrok-free.app/webhooks/superbank" }'

From a browser with webhook.site

webhook.site gives you an instant public URL to inspect deliveries without writing any handler code — useful for eyeballing payloads before you write parsing logic.

# Register the unique URL it generates
curl --request POST \
  --url https://api-sandbox.superbank.co/v0/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{ "url": "https://webhook.site/YOUR_UNIQUE_ID" }'

Save the secret from the response, then trigger a sandbox event (e.g., POST /v0/settlement-requests) and watch the delivery land in the webhook.site browser tab.

Event payload reference

The data object differs per event. Expand the relevant section for a worked example. All examples carry production-shape fields; sandbox and production payloads have identical shape.

payment.created

{
  "event": "payment.created",
  "data": {
    "id": "04621f85-bd40-46a9-a9a9-9fe14be09354",
    "type": "PAYIN",
    "status": "PENDING",
    "fee": "0.50000000",
    "source": {
      "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "100.00000000",
      "currency": "USDC",
      "rail": "SOLANA",
      "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "transaction_hash": null
    },
    "destination": {
      "account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "amount": "100.00000000",
      "currency": "USD",
      "rail": "ACH",
      "wallet_address": null,
      "transaction_hash": null
    },
    "created_at": "2026-01-26T14:12:08.354Z"
  },
  "timestamp": "2026-01-26T14:12:08.700Z"
}

payment.updated

{
  "event": "payment.updated",
  "data": {
    "id": "04621f85-bd40-46a9-a9a9-9fe14be09354",
    "type": "PAYIN",
    "status": "COMPLETED",
    "fee": "0.50000000",
    "settlement_request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "source": {
      "account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "100.00000000",
      "currency": "USDC",
      "rail": "SOLANA",
      "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "transaction_hash": "5aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX4yZ5aB6c"
    },
    "destination": {
      "account_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "amount": "100.00000000",
      "currency": "USD",
      "rail": "ACH",
      "wallet_address": null,
      "transaction_hash": null
    },
    "updated_at": "2026-01-26T15:48:08.670Z"
  },
  "timestamp": "2026-01-26T15:48:08.700Z"
}

settlement_request.created and settlement_request.updated

settlement_request.created

{
  "event": "settlement_request.created",
  "data": {
    "id": "39760060-846e-4d5a-8583-7ee62553f79b",
    "type": "STABLECOIN_TO_STABLECOIN",
    "payment_reason": "PERSONAL_TRANSFERS",
    "status": "REQUEST_STARTED",
    "amount": "20.00000000",
    "external_id": "txn_abc123",
    "metadata": { "user_id": "usr_42", "source": "mobile_app" },
    "source": null,
    "destination": {
      "currency": "USDC",
      "rail": "SOLANA",
      "is_third_party": true,
      "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "beneficiary": {
        "type": "BUSINESS",
        "business_name": "Acme Corp",
        "address": { "country_code": "US" }
      }
    },
    "payment_instructions": {
      "currency": "USDC",
      "rail": "SOLANA",
      "prefunded_wallet_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj"
    },
    "outbound_payment": null,
    "inbound_payment": null,
    "created_at": "2026-01-26T15:45:10.047Z",
    "updated_at": "2026-01-26T15:45:10.047Z",
    "processing_at": null,
    "completed_at": null,
    "reconciliation_expected_at": null,
    "failure_code": null,
    "failure_reason": null
  },
  "timestamp": "2026-01-26T15:45:10.100Z"
}

settlement_request.updated

{
  "event": "settlement_request.updated",
  "data": {
    "id": "39760060-846e-4d5a-8583-7ee62553f79b",
    "type": "STABLECOIN_TO_STABLECOIN",
    "payment_reason": "PERSONAL_TRANSFERS",
    "status": "SETTLEMENT_COMPLETED",
    "previous_status": "FUNDS_SENT",
    "amount": "20.00000000",
    "external_id": "txn_abc123",
    "metadata": { "user_id": "usr_42", "source": "mobile_app" },
    "source": null,
    "destination": {
      "currency": "USDC",
      "rail": "SOLANA",
      "is_third_party": true,
      "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "beneficiary": {
        "type": "BUSINESS",
        "business_name": "Acme Corp",
        "address": { "country_code": "US" }
      }
    },
    "payment_instructions": {
      "currency": "USDC",
      "rail": "SOLANA",
      "prefunded_wallet_address": "AWE1XaAdRuxzjqy8Q7q75MFbPTs1W6Zbp3zvYWcDGjTj"
    },
    "outbound_payment": {
      "id": "2a9d2a2c-d97b-4973-baf1-78e31d37a024",
      "type": "PAYOUT",
      "status": "COMPLETED",
      "amount": "20.00000000",
      "currency": "USDC",
      "created_at": "2026-01-26T15:45:51.589Z"
    },
    "inbound_payment": null,
    "created_at": "2026-01-26T15:45:10.047Z",
    "updated_at": "2026-01-26T15:48:08.670Z",
    "processing_at": "2026-01-26T15:45:51.594Z",
    "completed_at": "2026-01-26T15:48:08.657Z",
    "reconciliation_expected_at": "2026-01-29T15:45:51.594Z",
    "failure_code": null,
    "failure_reason": null
  },
  "timestamp": "2026-01-26T15:48:08.700Z"
}

account.created

{
  "event": "account.created",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "currency_code": "USDC",
    "rail": "SOLANA",
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "name": "USDC Account",
    "status": "ACTIVE",
    "balance": "0.00000000",
    "available_balance": "0.00000000",
    "created_at": "2026-01-26T14:12:08.354Z"
  },
  "timestamp": "2026-01-26T14:12:08.700Z"
}

account.updated

{
  "event": "account.updated",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "currency_code": "USDC",
    "rail": "SOLANA",
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "name": "USDC Account",
    "status": "ACTIVE",
    "balance": "1500.00000000",
    "available_balance": "1200.00000000",
    "reserved": "200.00000000",
    "updated_at": "2026-01-26T15:48:08.670Z"
  },
  "timestamp": "2026-01-26T15:48:08.700Z"
}

account.deleted

{
  "event": "account.deleted",
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "currency_code": "USDC",
    "rail": "SOLANA",
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "deleted_at": "2026-01-26T16:00:00.000Z"
  },
  "timestamp": "2026-01-26T16:00:00.100Z"
}

Next steps

Looking for the end-to-end on-ramping flow? See Real-Time On-Ramping — the section Detecting Completion shows where webhook events fit into the settlement lifecycle.

Guides

API Instructions

Core Resources

Changelog

Quick start

The basics

Supported events

Envelope and headers

Verifying signatures

Reliability

Retry policy

Common pitfalls

Testing

Test deliveries

From your local machine with ngrok

From a browser with webhook.site

Event payload reference

Next steps

​Quick start

​The basics

​Supported events

​Envelope and headers

​Verifying signatures

​Reliability

​Retry policy

​Common pitfalls

​Testing

​Test deliveries

​From your local machine with ngrok

​From a browser with webhook.site

​Event payload reference

​Next steps

Quick start

The basics

Supported events

Envelope and headers

Verifying signatures

Reliability

Retry policy

Common pitfalls

Testing

Test deliveries

From your local machine with ngrok

From a browser with webhook.site

Event payload reference

Next steps