Bank Hub Webhook Events

Bank Hub uses webhooks to notify your system of important events during the bank account linking or unlinking process in real-time.

Webhook Configuration

To receive webhook events, you need to provide a webhook URL to SePay Bank Hub. Create/Update Webhook API

Note

This is not the webhook for receiving balance change notifications. For balance change notifications, use IPN See IPN Details

General Webhook Event Structure

Each webhook event has the following standard structure:

Webhook Event

{
  "timestamp": 1768312100,
  "xid": "e61cdae9-505e-4349-9713-a3e5b8b80b5e",
  "version": "1.0",
  "event": "EVENT_NAME",
  "metadata": {

  }
}

Common fields:

timestampintegerrequired

Unix timestamp (seconds) when the event was created

xidstringrequired

Unique UUID of the event

versionstringrequired

Webhook API version (current: "1.0")

eventstringrequired

Event name (e.g., LINK_TOKEN_CREATED, BANK_ACCOUNT_LINKED)

metadataobjectrequired

Detailed event data, varies by event type

Bank Linking Flow

When a link token is created for the bank linking flow

LINK_TOKEN_CREATED

{
  "timestamp": 1768312100,
  "xid": "e61cdae9-505e-4349-9713-a3e5b8b80b5e",
  "version": "1.0",
  "event": "LINK_TOKEN_CREATED",
  "metadata": {
    "purpose": "LINK_BANK_ACCOUNT",
    "link_token_xid": "628af450-6f83-443f-b2f1-7d8ae4664e45",
    "link_session_xid": null
  }
}

When the user starts the linking session and is about to select a bank

LINK_SESSION_INITIALIZED

{
  "timestamp": 1768311902,
  "xid": "d5df6e97-689e-49ae-b380-08126c6da950",
  "version": "1.0",
  "event": "LINK_SESSION_INITIALIZED",
  "metadata": {
    "link_session_xid": "0e296f70-cf41-4e8f-a89f-00cee248b887",
    "link_token_xid": "ef4cb765-c297-4a51-a9eb-6f7a751978ae"
  }
}

When the user has selected a bank and navigated to the information entry screen

LINK_SESSION_STATE_CHANGED - REQUEST_BANK_ACCOUNT_LINK

{
  "timestamp": 1768312140,
  "xid": "e117249c-a827-4f89-951d-433c3a384785",
  "version": "1.0",
  "event": "LINK_SESSION_STATE_CHANGED",
  "metadata": {
    "state": "REQUEST_BANK_ACCOUNT_LINK",
    "brand_name": "MBBank",
    "account_type": "personal",
    "link_token_xid": "628af450-6f83-443f-b2f1-7d8ae4664e45",
    "link_session_xid": "a9e6d327-5888-449a-b82a-356fa80d6211"
  }
}

When the user has entered account information and navigated to the OTP entry screen

LINK_SESSION_STATE_CHANGED

{
  "timestamp": 1768311997,
  "xid": "a67f03a1-1bdf-46a5-8c6e-4af6aec28aca",
  "version": "1.0",
  "event": "LINK_SESSION_STATE_CHANGED",
  "metadata": {
    "state": "CONFIRM_BANK_ACCOUNT_LINK",
    "brand_name": "MBBank",
    "account_type": "personal",
    "account_number": "0000000000011111",
    "account_holder_name": "NGUYEN VAN A",
    "link_token_xid": "ef4cb765-c297-4a51-a9eb-6f7a751978ae",
    "link_session_xid": "0e296f70-cf41-4e8f-a89f-00cee248b887"
  }
}

When the linking process is successfully completed, 3 webhook events are sent:

LINK_SESSION_STATE_CHANGED - FINISHED_BANK_ACCOUNT_LINK

{
  "timestamp": 1768312172,
  "xid": "21e2445d-9696-4edd-816c-746b2e6ec110",
  "version": "1.0",
  "event": "LINK_SESSION_STATE_CHANGED",
  "metadata": {
    "state": "FINISHED_BANK_ACCOUNT_LINK",
    "brand_name": "MBBank",
    "account_type": "personal",
    "account_number": "0000000000011111",
    "account_holder_name": "NGUYEN VAN A",
    "link_token_xid": "628af450-6f83-443f-b2f1-7d8ae4664e45",
    "link_session_xid": "a9e6d327-5888-449a-b82a-356fa80d6211"
  }
}

BANK_ACCOUNT_LINKED

{
  "timestamp": 1768312023,
  "xid": "e343bdec-97dc-4c60-b953-f81b183e0096",
  "version": "1.0",
  "event": "BANK_ACCOUNT_LINKED",
  "metadata": {
    "bank_account_xid": "587eabfb-f086-11f0-b16e-52c7e9b4f41b",
    "brand_name": "MBBank",
    "account_type": "personal",
    "account_number": "0000000000011111",
    "link_token_xid": "ef4cb765-c297-4a51-a9eb-6f7a751978ae",
    "link_session_xid": "0e296f70-cf41-4e8f-a89f-00cee248b887"
  }
}

LINK_SESSION_COMPLETED

{
  "timestamp": 1768312173,
  "xid": "19b3bbb2-41a3-4b27-a301-db91a036fb18",
  "version": "1.0",
  "event": "LINK_SESSION_COMPLETED",
  "metadata": {
    "bank_account_xid": "b1293181-f086-11f0-b16e-52c7e9b4f41b",
    "link_token_xid": "628af450-6f83-443f-b2f1-7d8ae4664e45",
    "link_session_xid": "a9e6d327-5888-449a-b82a-356fa80d6211"
  }
}

Unlinking Flow

When a link token is successfully created for the bank unlinking flow:

LINK_TOKEN_CREATED

{
  "timestamp": 1768443727,
  "xid": "3406b960-71e4-4fdd-9bb3-41bba8fe6107",
  "version": "1.0",
  "event": "LINK_TOKEN_CREATED",
  "metadata": {
    "purpose": "UNLINK_BANK_ACCOUNT",
    "link_token_xid": "378c3028-a366-4aaa-90d4-56e0047d92ce",
    "link_session_xid": null
  }
}

When the user starts the unlinking process and navigates to the confirmation (OTP) screen

LINK_SESSION_STATE_CHANGED

{
  "timestamp": 1768443767,
  "xid": "a3d04fca-226c-4376-ac31-189283801f1b",
  "version": "1.0",
  "event": "LINK_SESSION_STATE_CHANGED",
  "metadata": {
    "state": "REQUEST_BANK_ACCOUNT_UNLINK",
    "brand_name": "ACB",
    "account_type": "individual",
    "account_number": "7777777777",
    "link_token_xid": "378c3028-a366-4aaa-90d4-56e0047d92ce",
    "link_session_xid": "53f42c84-ada6-442a-8732-6d8ec686cdc0"
  }
}

When the bank account is successfully unlinked (unlinked from the bank)

LINK_SESSION_COMPLETED

{
  "timestamp": 1768443806,
  "xid": "76e32fa6-5ed2-42b6-9f57-7cb8acbd12dc",
  "version": "1.0",
  "event": "LINK_SESSION_COMPLETED",
  "metadata": {
    "bank_account_xid": "54a488a6-f1b8-11f0-b21a-a6006ab65aca",
    "unlinked": true,
    "link_token_xid": "378c3028-a366-4aaa-90d4-56e0047d92ce",
    "link_session_xid": "53f42c84-ada6-442a-8732-6d8ec686cdc0"
  }
}

BANK_ACCOUNT_UNLINKED | BANK_ACCOUNT_INACTIVED

{
  "timestamp": 1768443805,
  "xid": "3c02781a-e061-44a0-b035-0cab9d00f73c",
  "version": "1.0",
  "event": "BANK_ACCOUNT_UNLINKED | BANK_ACCOUNT_INACTIVED",
  "metadata": {
    "bank_account_xid": "54a488a6-f1b8-11f0-b21a-a6006ab65aca",
    "brand_name": "ACB",
    "account_type": "individual",
    "account_number": "7777777777",
    "link_token_xid": "378c3028-a366-4aaa-90d4-56e0047d92ce",
    "link_session_xid": "53f42c84-ada6-442a-8732-6d8ec686cdc0"
  }
}

Note

BANK_ACCOUNT_UNLINKED: Direct unlinking from the bank
BANK_ACCOUNT_INACTIVED: Only deactivated without direct unlinking from the bank

Webhook Retry

SePay will retry webhooks if the network connection to the webhook URL fails. Additionally, you can choose conditions supported by SePay to enable webhook retries. The retry interval is in minutes, increasing according to the Fibonacci sequence

Maximum retry attempts: 7 times
Maximum duration: 5 hours from the first failed call
SePay's network connect timeout: 5 seconds
SePay's maximum response wait time: 8 seconds

Note

SePay will NOT retry webhooks if the status is failed but the network connection is successful, unless that webhook has retry conditions configured and only retries when one of the configured conditions is met.

Next Steps

After configuring webhook events, you can:

Balance Change Notifications (IPN) - Receive real-time transaction notifications
Update Webhook API - Update webhook URL via API
Bank Account List API - View linked bank accounts
Transaction List API - Query transaction history