Create Webhooks

Steps to Integrate WebHooks

• Step 1: Go to the WebHooks menu

• Step 2: Click the + Add webhooks button at the top right

  

• Step 3: Fill in all required information, including:

  • Name: Any name you want

  1. Select Event: You can choose to trigger WebHooks when money in, money out, or both

  2. Select Conditions: Including:

     • When bank account is: Choose the bank account(s) for which WebHooks will trigger. If you want to specify virtual accounts (VA) to receive notifications, check Filter by virtual account and select the desired VA accounts.
     • Ignore if transaction content does not contain payment code: If selected, SePay will NOT send WebHooks if the payment code is not detected in the transfer content. > TIP: Configure payment code recognition under Company → General Settings → Payment Code Structure

  3. WebHooks Attributes: Including:

     • Call URL: The link where WebHooks will be sent. If you want to build a website to receive webhooks, see the guide here.
     • Is this a payment verification WebHook?: Select Yes if this WebHook is used to verify payments for your website/application.
     • Retry WebHook when: SePay supports certain conditions to automatically retry WebHooks when:
       • The HTTP Status Code is not between 200 and 299.

  4. WebHooks Authentication Configuration: Including:

     • Authentication Type: SePay currently supports OAuth 2.0, API Key, or No authentication.
       • If OAuth 2.0 is selected, fill in OAuth 2.0 Access Token URL, Client ID, and Client Secret.
       • If No authentication or API Key is selected, choose Request Content Type as application/json, multipart/form-data, or application/x-www-form-urlencoded according to your receiver application.

• Step 4: Click [Add] to complete integration.

WebHooks Payload Data

• SePay sends a POST request with the following JSON payload:

{
  "id": 92704,
  "gateway": "Vietcombank",
  "transactionDate": "2023-03-25 14:02:37",
  "accountNumber": "0123499999",
  "code": null,
  "content": "transfer to buy iphone",
  "transferType": "in",
  "transferAmount": 2277000,
  "accumulated": 19077000,
  "subAccount": null,
  "referenceCode": "MBVCB.3278907687",
  "description": ""
}

• Parameter Explanation

Testing WebHooks

• If using a Demo account, go to Transactions → Simulate Transaction to create a new test transaction. See details about Simulate Transaction here.

• If not using a demo account, you can test by sending a small amount to trigger a real transaction.

• Then go to Logs → WebHooks Log to view sent WebHooks.

• You can also view the WebHooks message per transaction at ⇆ Transactions → Auto column → select Pay.

Recognizing Successful WebHooks

• When receiving a WebHook from SePay, your website must respond as follows for SePay to mark it successful:

  • With OAuth 2.0 authentication (See OAuth2 configuration guide for Webhooks integration)

    • The response body must be JSON containing success: true: {"success": true, ....}
    • HTTP Status Code must be 201

  • With API Key authentication

    • The response body must be JSON containing success: true: {"success": true, ....}
    • HTTP Status Code must be 201 or 200

  • Without authentication

    • The response body must be JSON containing success: true: {"success": true, ....}
    • HTTP Status Code must be 201 or 200

• If the response does not meet the above conditions, SePay will consider the webhook failed.

Automatic Retry for WebHooks

• SePay will retry WebHooks if the network connection to the webhook URL fails. Additionally, you can configure retry conditions supported by SePay. The retry intervals follow the Fibonacci sequence.

  • Maximum retry attempts: 7
  • Maximum total retry duration: 5 hours from the first failed attempt
  • Network connection timeout: 5 seconds
  • Maximum response timeout: 8 seconds
  Note

  SePay will NOT retry a webhook if the connection is successful but the webhook status is failed, unless the retry conditions you set are met.

Preventing Duplicate Transactions

• To avoid duplicate transactions in case of retry issues, SePay recommends implementing duplicate transaction prevention in your webhook receiver.

• Validate the uniqueness of the id field, or combine it with fields such as referenceCode, transferType, and transferAmount from SePay's payload to ensure transaction uniqueness.

Manual Retry for WebHooks

• You can manually trigger a webhook retry by going to Transaction Details → View Sent WebHooks → Retry, or by visiting the WebHooks Log and selecting Retry.