Webhooks

Understanding Webhooks

Webhooks provide a powerful way to receive real-time notifications about events occurring in your UnblockPay transactions. Instead of continuously polling our API for updates, webhooks push information to your system as soon as events happen.

When an event occurs (like a transaction status change), UnblockPay will send an HTTP POST request to the URL you specify. This enables your application to:

• Automatically update your internal systems when transaction statuses change

• Track the progress of payments in real-time

• Trigger your own business logic based on payment events

• Maintain accurate records without constant API polling

How to create or manage a webhook configuration

Create a new webhook configuration

To set it up, make a POST request to /v1/webhook-configs with:

• The list of events (listed below in Event types) you want to subscribe to in the subscriptions field

• Your webhook URL where you'll receive the events

• Set enabled to true to begin listening for events. If enabled is omitted, it defaults to false — set it to true to begin receiving events immediately.

Each partner may have only one webhook configuration.

Attempting to create a second configuration returns a 422 error with the code webhook_config_already_exists. Use PUT /v1/webhook-configs/{id} to update an existing configuration.

Below is an example request to our webhook endpoint:

curl https://api.sandbox.unblockpay.com/v1/webhook-configs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "url": "https://your-app.example.com/webhooks/unblockpay",
    "subscriptions": ["payout.completed", "payout.failed", "payin.completed"],
    "enabled": true
  }'

You will get a response like:

{
  "id": "d4e5f6a7-0010-7000-8000-001122334455",
  "partner_id": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://your-app.example.com/webhooks/unblockpay",
  "subscriptions": ["payout.completed", "payout.failed", "payin.completed"],
  "enabled": true,
  "created_at": "2024-03-15T14:30:00Z",
  "updated_at": "2024-03-15T14:30:00Z"
}

Update the current webhook configuration

You can update your webhook configuration at any time by making a PUT request to /v1/webhook-configs/{id} to:

• Modify which events you want to receive

• Change your webhook receiving URL

• Set enabled to true or false to enable or disable webhook notifications

Below is an example request to update webhook configuration:

curl https://api.sandbox.unblockpay.com/v1/webhook-configs/d4e5f6a7-0010-7000-8000-001122334455 \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "url": "https://your-app.example.com/webhooks/unblockpay-v2",
    "subscriptions": [
      "payout.completed",
      "payout.failed",
      "payout.error",
      "payin.completed",
      "customer.approved",
      "customer.rejected"
    ],
    "enabled": true
  }'

Response example:

{
  "id": "d4e5f6a7-0010-7000-8000-001122334455",
  "partner_id": "123e4567-e89b-12d3-a456-426614174000",
  "url": "https://your-app.example.com/webhooks/unblockpay-v2",
  "subscriptions": [
    "payout.completed",
    "payout.failed",
    "payout.error",
    "payin.completed",
    "customer.approved",
    "customer.rejected"
  ],
  "enabled": true,
  "created_at": "2024-03-15T14:30:00Z",
  "updated_at": "2024-03-22T10:15:00Z"
}

To pause event delivery without deleting the configuration, set enabled to false

Event types

Below are all available webhook event types.

Fiat to Stablecoin (Pay-in)

Stablecoin to Fiat (Payout)

Stablecoin Transfer

Customer

External Account

Virtual Account

Event structure

For every event, the payload includes the following fields:

Below is an example payload for a created payout:

{
  "event": "payout",
  "event_id": "4d7196d0-ed6e-11ef-8fc7-7b1bb8f06792",
  "event_type": "payout.created",
  "event_resource_id": "23449700-0375-11f0-a25c-7da3b4c9befc",
  "event_resource_status": "awaiting_deposit",
  "event_resource": {},
  "event_created_at": "2025-03-17T21:16:49.711Z"
}

Testing webhooks in sandbox environment

In the sandbox environment, UnblockPay does not send real webhooks. Instead, you can trigger mocked event payloads that are delivered to your registered URL. To test, send a POST request to /webhooks/mock with the desired event_type.

Mocked events are currently supported for payout, payin, and walletTransfer event types.

Here is a request example in sandbox environment:

{
    "event_type": "payout.processing"
}

Webhooks API endpoints