UnblockPayGuideReference

Webhooks

Understanding WebhooksCopied!

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

Webhooks API endpointsCopied!

  • POST/webhooks: Create a new webhook configuration

  • GET/webhooks: Retrieve the current webhook configuration

  • PUT/webhooks: Update the current webhook configuration

Webhook configurationCopied!

1) Create a new webhook configurationCopied!

For implementing and activating webhooks in your application, make a POST request to /webhooks 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

Below is an example request to our webhook endpoint:

curl https://api.sandbox.unblockpay.com/webhooks \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
  "enabled": true,
  "subscriptions": [
    "payout.processing", "payout.completed"
  ],
  "url": "https://fintech.xyz/abc-123"
}'

You will get a response like:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "partner_id": "123e4567-e89b-12d3-a456-426614174000",
  "subscriptions": [
    "payout.processing", "payout.completed"
  ],
  "url": "https://fintech.xyz/abc-123",
  "enabled": true,
  "created_at": "2025-05-18T16:46:12.093Z",
  "updated_at": "2025-05-18T16:46:12.093Z"
}

2) Update the current webhook configurationCopied!

You can update your webhook configurations anytime by making a PUT request to /webhooks 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/webhooks \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: YOUR_SECRET_TOKEN' \
  --data '{
    "enabled": true
    "subscriptions": [
      "payout.created", "payout.processing", "payout.completed", "payout.cancelled", "payout.failed", "payout.refunded", "payout.error"
    ],
    "url": "https://fintech.xyz/abc-789", 
}'

Response example:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "partner_id": "123e4567-e89b-12d3-a456-426614174000",
  "subscriptions": [
      "payout.created", "payout.processing", "payout.completed", "payout.cancelled", "payout.failed", "payout.refunded", "payout.error"
    ],
  "url": "https://fintech.xyz/abc-789",
  "enabled": true,
  "created_at": "2025-05-18T16:46:12.093Z",
  "updated_at": "2025-05-18T16:46:12.093Z"
}

Event typesCopied!

Below are all available webhook event types:

1) Pay-insCopied!

  • payin.created: Event triggered when a new pay-in request is initially created.

  • payin.processing: Sent when UnblockPay confirms receipt of the fiat deposit and begins processing the transaction.

  • payin.completed: Indicates that the pay-in has been successfully processed and funds have been delivered to the recipient.

  • payout.cancelled: Triggered when a payin is cancelled, which can only occur while in the awaiting_deposit status.

  • payout.failed: Indicates that the pay-in transaction has failed to process successfully.

  • payout.refunded: Signifies that the funds have been returned to the sender.

2) PayoutsCopied!

  • payout.created: Event triggered when a new payout request is initially created.

  • payout.processing: Sent when UnblockPay confirms receipt of the stablecoin deposit and begins processing the transaction.

  • payout.completed: Indicates that the payout has been successfully processed and funds have been delivered to the recipient.

  • payout.cancelled: Triggered when a payout is cancelled, which can only occur while in the awaiting_deposit status.

  • payout.failed: Indicates that the payout transaction has failed to process successfully.

  • payout.refunded: Signifies that the funds have been returned to the sender.

Event structureCopied!

We have released webhooks for Pay-in and Payouts and plan to expand support to additional event categories soon.

For every event, we will have the following structure:

  • event: The transaction type (currently only payin and payout)

  • event_id: The unique identifier of the event

  • event_type: One of the event types listed in Webhooks

  • event_resource_id: The unique identifier of the transaction

  • event_resource_status: One of the transaction states listed in Transactions

  • event_resource: The complete transaction object

  • event_created_at: The timestamp when the event occurred

Below is an example of an event 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 environmentCopied!

In the sandbox environment, we don't send real webhooks. Instead, we provide mocked webhook events for testing. You can trigger these events by making requests to our sandbox endpoint and specifying which event type you want to receive.

To test webhooks in sandbox, send a POST request to the /webhooks/mock endpoint with the desired event_type (listed above). The webhook will be delivered to your registered URL.

Here is a request example in sandbox environment:

{
    "event_type": "payout.processing"
}

© 2025 UnblockPay