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

Webhook configurationCopied!

For implementing and activating webhooks in your application, make a POST request to /webhooks with:

• The list of events (listed below) 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:

{
    "subscriptions": ["payout.created", "payout.processing", "payout.completed", "payout.cancelled", "payout.failed", "payout.refunded", "payout.error"],
    "url": "https://fintech.xyz/abc-123",
    "enabled": true
}

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

• Enable or disable webhook notifications

Event typesCopied!

Below are all available webhook event types:

• 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.

Testing webhooks in sandboxCopied!

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"
}