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

    NameTypeRequiredDescription
    webhook_url
    stringNot required
    Filter by webhook URL (partial match)
    api_key
    stringNot required
    Filter by API key
    active
    integerNot required
    Filter by active status (0: inactive, 1: active)
    page
    integerNot required
    Page number, starting from 1
    limit
    integerNot required
    Number of results per page

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

    NameTypeRequiredDescription
    id
    integerRequired
    Webhook ID

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

    NameTypeRequiredDescription
    bank_account_id
    integerRequired
    Bank account ID
    name
    stringRequired
    Webhook name
    event_type
    stringRequired
    Event type (All, In_only, Out_only)
    authen_type
    stringRequired
    Authentication type (No_Authen, OAuth2.0, Api_Key)
    webhook_url
    stringRequired
    Webhook receiving URL
    is_verify_payment
    integerRequired
    Verify payment (0: no, 1: yes)
    skip_if_no_code
    integerNot required
    Skip if there is no payment code (0: no, 1: yes)
    active
    integerNot required
    Active status (0: inactive, 1: active)
    retry_conditions
    arrayNot required
    Retry conditions when errors occur
    only_va
    integerNot required
    Only receive transactions from virtual accounts (0: no, 1: yes)
    bank_sub_account_ids
    arrayNot 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

    NameTypeRequiredDescription
    id
    integerRequired
    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.

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

    NameTypeRequiredDescription
    id
    integerRequired
    Webhook ID

Error codes

  • Below are possible error codes when using the webhooks API:
    HTTP CodeError CodeDescription
    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