Webhooks API

Documentation on using the webhooks API through OAuth2 in SePay.

Introduction

SePay's Webhooks API allows you to manage webhooks to receive real-time transaction notifications. Webhooks are an efficient way to automate payment processes, helping your system receive notifications immediately when new transactions occur.

To use this API, you need the corresponding permissions in the Access Token scope: webhook:read to view, webhook:write to create/update, and webhook:delete to delete webhooks.

Endpoints

The Webhooks API provides the following endpoints:

GET

/api/v1/webhooks

Get list of webhooks with filter options

GET

/api/v1/webhooks/{id}

Get detailed information about a specific webhook

POST

/api/v1/webhooks

Create a new webhook

PATCH

/api/v1/webhooks/{id}

Update webhook information

DELETE

/api/v1/webhooks/{id}

Delete a webhook

Get Webhook List

GET

/api/v1/webhooks

Authorization: Bearer {YOUR_ACCESS_TOKEN}

This endpoint returns a list of webhooks for your company. You can filter results by various criteria.

Required permissions:

Scope: webhook:read
User permission: Webhooks (View webhooks list)

Query parameters:

webhook_urlstring

Filter by webhook URL (partial search)

api_keystring

Filter by API key

activeinteger

Filter by active status (0: inactive, 1: active)

pageinteger

Page number, starting from 1

limitinteger

Number of results per page

curl -G "https://my.sepay.vn/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode "active=1" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"

RESPONSE

{
    "status": "success",
    "data": [
        {
            "id": 23,
            "bank_account_id": 19,
            "name": "Online shop integration",
            "event_type": "In_only",
            "authen_type": "Api_Key",
            "webhook_url": "https://example.com/webhook/payment",
            "is_verify_payment": true,
            "skip_if_no_code": true,
            "retry_conditions": {
                "non_2xx_status_code": 0
            },
            "only_va": true,
            "active": true,
            "created_at": "2025-02-15 14:23:56",
            "api_key": "a7c3b4e5f6a7b8c9d0e1f2a3b4c5d6e7",
            "request_content_type": "Json",
            "bank_sub_account_ids": [25, 26]
        },
        {
            "id": 22,
            "bank_account_id": 18,
            "name": "CRM integration",
            "event_type": "All",
            "authen_type": "OAuth2.0",
            "webhook_url": "https://crm.example.com/webhook/transactions",
            "is_verify_payment": false,
            "skip_if_no_code": false,
            "retry_conditions": {
                "non_2xx_status_code": 0
            },
            "only_va": false,
            "active": true,
            "created_at": "2025-02-10 09:45:32",
            "oauth2_client_id": "client_id_example",
            "oauth2_client_secret": "client_secret_example",
            "oauth2_access_token_url": "https://crm.example.com/oauth/token"
        }
    ],
    "meta": {
        "pagination": {
            "total": 5,
            "per_page": 20,
            "current_page": 1,
            "last_page": 1
        }
    }
}

Get Webhook Details

GET

/api/v1/webhooks/{id}

Authorization: Bearer {YOUR_ACCESS_TOKEN}

This endpoint returns detailed information of a webhook based on ID.

Required permissions:

Scope: webhook:read
User permission: Webhooks (View webhooks list)

Path parameters:

idintegerrequired

Webhook ID

curl -X GET "https://my.sepay.vn/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE

{
    "status": "success",
    "data": {
        "id": 23,
        "bank_account_id": 19,
        "name": "Online shop integration",
        "event_type": "In_only",
        "authen_type": "Api_Key",
        "webhook_url": "https://example.com/webhook/payment",
        "is_verify_payment": true,
        "skip_if_no_code": true,
        "retry_conditions": {
            "only_va": true,
            "active": true,
            "created_at": "2025-02-15 14:23:56",
            "api_key": "a7c3b4e5f6a7b8c9d0e1f2a3b4c5d6e7",
            "request_content_type": "Json",
            "bank_sub_account_ids": [25, 26]
        }
    }
}

Create New Webhook

POST

/api/v1/webhooks

Authorization: Bearer {YOUR_ACCESS_TOKEN}
Content-Type: application/json

This endpoint allows you to create a new webhook to receive transaction notifications.

Required permissions:

Scope: webhook:write
User permission: Webhooks (Add webhooks)

Request parameters:

bank_account_idintegerrequired

Bank account ID

namestringrequired

Webhook name

event_typestringrequired

Event type (All, In_only, Out_only)

authen_typestringrequired

Authentication type (No_Authen, OAuth2.0, Api_Key)

webhook_urlstringrequired

Webhook receiving URL

is_verify_paymentintegerrequired

Verify payment (0: no, 1: yes)

skip_if_no_codeinteger

Skip if no payment code (0: no, 1: yes)

activeinteger

Active status (0: inactive, 1: active)

retry_conditionsarray

Retry conditions on error

only_vainteger

Only receive transactions from virtual account (0: no, 1: yes)

bank_sub_account_idsarray

List of virtual account IDs (required if only_va=1)

Additional parameters for each authentication type:

OAuth2.0:

oauth2_access_token_url (required) – URL to get access token
oauth2_client_id (required) – Client ID
oauth2_client_secret (required) – Client Secret

Api_Key:

api_key (required) – API Key for authentication
request_content_type (required) – Request content type (Json, multipart_form-data)

No_Authen:

request_content_type (required) – Request content type (Json, multipart_form-data)

curl -X POST "https://my.sepay.vn/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "bank_account_id": 19,
    "name": "Online shop integration",
    "event_type": "In_only",
    "authen_type": "Api_Key",
    "webhook_url": "https://example.com/webhook/payment",
    "is_verify_payment": 1,
    "skip_if_no_code": 1,
    "active": 1,
    "only_va": 1,
    "bank_sub_account_ids": [25, 26],
    "retry_conditions": {"non_2xx_status_code": 1},
    "api_key": "a7c3b4e5f6a7b8c9d0e1f2a3b4c5d6e7",
    "request_content_type": "Json"
  }'

RESPONSE

{
  "message": "WebHook added successfully",
  "id": 23
}

Update Webhook

PATCH

/api/v1/webhooks/{id}

Authorization: Bearer {YOUR_ACCESS_TOKEN}
Content-Type: application/json

This endpoint allows you to update information of an existing webhook.

Required permissions:

Scope: webhook:write
User permission: Webhooks (Edit webhooks)

Path parameters:

idintegerrequired

Webhook ID

Request parameters: Same as when creating a webhook, but all are optional. You only need to provide the parameters you want to change.

curl -X PATCH "https://my.sepay.vn/api/v1/webhooks/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "active": 0,
    "skip_if_no_code": 0
  }'

RESPONSE

{
    "message": "WebHook updated successfully",
    "id": "23"
}

Delete Webhook

DELETE

/api/v1/webhooks/{id}

Authorization: Bearer {YOUR_ACCESS_TOKEN}

This endpoint allows you to delete a webhook.

Required permissions:

Scope: webhook:delete
User permission: Webhooks (Delete webhooks)

Path parameters:

idintegerrequired

Webhook ID

curl -X DELETE "https://my.sepay.vn/api/v1/webhooks/{id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

RESPONSE

{
    "message": "WebHook deleted successfully"
}

Error Codes

Below are the error codes that may be encountered when using the Webhooks API:

400validation_error

Input data validation error

401unauthorized

Token is invalid or expired

403forbidden

No permission to access this resource

404not_found

Webhook not found