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:
/api/v1/webhooksGet list of webhooks with filter options
/api/v1/webhooks/{id}Get detailed information about a specific webhook
/api/v1/webhooksCreate a new webhook
/api/v1/webhooks/{id}Update webhook information
/api/v1/webhooks/{id}Delete a webhook
Get Webhook List
/api/v1/webhooksAuthorization: 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:
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"
{
"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
/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:
curl -X GET "https://my.sepay.vn/api/v1/webhooks/{id}" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
{
"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
/api/v1/webhooksAuthorization: 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:
Additional parameters for each authentication type:
OAuth2.0:
oauth2_access_token_url(required) – URL to get access tokenoauth2_client_id(required) – Client IDoauth2_client_secret(required) – Client Secret
Api_Key:
api_key(required) – API Key for authenticationrequest_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"}'
{
"message": "WebHook added successfully",
"id": 23
}Update Webhook
/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:
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}'
{
"message": "WebHook updated successfully",
"id": "23"
}Delete Webhook
/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:
curl -X DELETE "https://my.sepay.vn/api/v1/webhooks/{id}" \-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
{
"message": "WebHook deleted successfully"
}Error Codes
Below are the error codes that may be encountered when using the Webhooks API:
400validation_errorInput data validation error
401unauthorizedToken is invalid or expired
403forbiddenNo permission to access this resource
404not_foundWebhook not found