Webhooks API

Documentation on how to use the webhooks API via OAuth2 in SePay.

Introduction

SePay’s Webhooks API lets you manage webhooks to receive real-time notifications about transactions. Webhooks are an efficient way to automate payment workflows, allowing your system to be notified immediately when a new transaction occurs.
To use this API, your Access Token must include the appropriate scopes: 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 a list of webhooks with filtering 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 a webhook

DELETE

/api/v1/webhooks/{id}

Delete a webhook

Get webhook list

GET

/api/v1/webhooks

Authorization: Bearer {YOUR_ACCESS_TOKEN}

This endpoint returns the list of webhooks for your company. You can filter results by various criteria.
Required permissions
- Scope: webhook:read
- User permission: Webhooks (View webhook list)

Query parameters

Name	Type	Required	Description
`webhook_url`	string	Not required	Filter by webhook URL (partial match)
`api_key`	string	Not required	Filter by API key
`active`	integer	Not required	Filter by active status (0: inactive, 1: active)
`page`	integer	Not required	Page number, starting from 1
`limit`	integer	Not required	Number of results per page

RESPONSE

{
  "status": "success",
  "data": [
    {
      "id": 23,
      "bank_account_id": 19,
      "name": "Integration with online shop",
      "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": "Integration with CRM",
      "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 by its ID.
Required permissions
- Scope: webhook:read
- User permission: Webhooks (View webhook list)
Path parameters
Name Type Required Description
id
integer Required
Webhook ID

Name	Type	Required	Description
`id`	integer	Required	Webhook ID

RESPONSE

{
  "status": "success",
  "data": {
    "id": 23,
    "bank_account_id": 19,
    "name": "Integration with online shop",
    "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 a new webhook

POST

/api/v1/webhooks

Authorization: Bearer {YOUR_ACCESS_TOKEN}

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

Name	Type	Required	Description
`bank_account_id`	integer	Required	Bank account ID
`name`	string	Required	Webhook name
`event_type`	string	Required	Event type (All, In_only, Out_only)
`authen_type`	string	Required	Authentication type (No_Authen, OAuth2.0, Api_Key)
`webhook_url`	string	Required	Webhook receiving URL
`is_verify_payment`	integer	Required	Verify payment (0: no, 1: yes)
`skip_if_no_code`	integer	Not required	Skip if there is no payment code (0: no, 1: yes)
`active`	integer	Not required	Active status (0: inactive, 1: active)
`retry_conditions`	array	Not required	Retry conditions when errors occur
`only_va`	integer	Not required	Only receive transactions from virtual accounts (0: no, 1: yes)
`bank_sub_account_ids`	array	Not required	List of virtual account IDs (required if only_va=1)

Additional parameters for each authentication type:
- 🔐 OAuth2.0
  - Additional configuration parameters:
    - oauth2_access_token_url (required) – URL to obtain the access token.
    - oauth2_client_id (required) – Client ID.
    - oauth2_client_secret (required) – Client Secret.
- 🔑 Api_Key
  - Additional configuration parameters:
    - api_key (required) – API Key used for authentication.
    - request_content_type (required) – Request content type (Json, multipart_form-data).
- 🚫 No_Authen
  - Additional configuration parameters:
    - request_content_type (required) – Request content type (Json, multipart_form-data).

Update a webhook

PATCH

/api/v1/webhooks/{id}

Authorization: Bearer {YOUR_ACCESS_TOKEN}

This endpoint allows you to update an existing webhook.
Required permissions
- Scope: webhook:write
- User permission: Webhooks (Edit webhooks)
Path parameters
Name Type Required Description
id
integer Required
Webhook ID
Request parameters
- The request parameters are the same as when creating a webhook, but all are optional. Provide only the parameters you want to change.

Name	Type	Required	Description
`id`	integer	Required	Webhook ID

Delete a 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
Name Type Required Description
id
integer Required
Webhook ID

Name	Type	Required	Description
`id`	integer	Required	Webhook ID

Error codes

Below are possible error codes when using the webhooks API:

HTTP Code	Error Code	Description
400	validation_error	Input data validation error
401	unauthorized	Token is invalid or expired
403	forbidden	You do not have permission to access this resource
404	not_found	Webhook not found