Platform Webhook Notifications

Webhooks are automated messages sent from our servers to make you aware of various events.

After you've subscribed to a webhook, you can let your app execute code immediately after specific events occur, instead of having to make API calls periodically to check their status.

Available webhooks


  • You can have multiple subscriptions per each webhook.
  • After 5 failed notifications you will receive an email warning you of the issue.
  • After 15 failed notifications (we couldn’t reach your URL), the hook will be automatically invalidated.
  • The URL that we hook must respond with a 2XX status code within 10 seconds – otherwise it will be considered as a failure
  • You are strongly advised to do a GET on the resource to check its status.

Configure a webhook using the API

Setup new webhook: make a POST /webhooks request:

curl --request POST \
  --url '' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PLATFORM_SECRET_KEY>' \
  --data-raw '{
  	"webhookName": "authorization/update",
    "email": "[email protected]",
    "url": "" 

Modify existing webhook: make a PATCH /webhooks/{webhookId} request:

curl --request PATCH \
  --url '{webhookId}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PLATFORM_SECRET_KEY>' \
  --data-raw '{
    "url": "" 

Delete existing webhook: make a DELETE /webhooks/{webhookId} request:

curl --request DELETE \
  --url '{webhookId}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PLATFORM_SECRET_KEY>'

Verifying webhooks

Webhooks created through the API are verified by calculating a digital signature. Each webhook request includes a base64-encoded X-Hmac-SHA256 header, which is generated using the <PLATFORM_SECRET_KEY> along with the data sent in the request.

To verify that the request came from UNIPaaS, compute the HMAC digest according to the following algorithm and compare it to the value in the X-Hmac-SHA256 header. If they match, then you can be sure that the webhook was sent from UNIPaaS.

const express = require('express')
const bodyParser = require('body-parser');
const { createHmac } = require('crypto');
const app = express();


app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.raw());'/webhook', function (req, res) {
  const {headers, body} = req;
  const signedHeader = headers["x-hmac-sha256"];
  const hash = createHmac('sha256', SECRET)
  const buff = new Buffer(hash);
  const calculated =  buff.toString('base64');

  if (calculated === signedHeader) {
    console.log('hook verified successfully')
  else {
    console.log('failed to verify hook!')

  res.send('Hello World')



If there are any status changes to a vendor's onboarding, you'll receive a webhook notification to your server, indicating the current status.

Available webhooks:

  • onboarding/update

Please refer to the onboarding Webhook Notifications page to learn more about onboarding webhooks and review examples.


On every new Authorization or Authorization status change, you will receive a webhook notification to your server.

Available webhooks:

  • authorization/update

The body will include the AuthorizationResult object:

ParameterAlways AvailableTypeDescription
authorizationIdYesStringUnique ID of the Object
authorizationStatusYesEnumThe status of the Authorization. See below detailed information
paymentOptionResultYesEnumThe payment Option details
currencyYesStringThe Currency of the payment
amountYesNumberThe Amount of the payment
orderIdYesStringUnique ID form the merchant system
processorYesObjectAdditional data from the acquirer.
itemsYesObjectThe items of the order per item per vendor
transactionIdYesStringThe transaction ID of the specific payment operation


Account notifications are created to notify you when your vendor receives money for the first time - creating an automatic account in the accepted currency. Each time an account balance is created or disabled, you'll get a webhook notification to your server, indicating its current status.

Available webhooks:

  • ewallet/create

The body will include the following object:

ParameterAlways AvailableTypeDescription
eWalletIdyesstringAccount unique identifier
vendorIdnostringThe unique ID of the vendor's Account.
If the Account belongs to the platform, it will return null
platformIdyesstringUnique ID of the platform
currencyyesenumUSD, GBP, EUR


Payout notifications notify you of every newly created payout and any change in the status of a payout. The webhook notification gets sent to your server.

Available webhooks:

  • payout/update

The body will include the PayoutResult object:

ParameterAlways AvailableTypeDescription


Sending Vendor emails from your system

In case you plan to use these webhook notifications to send emails from your system, you should communicate that to UNIPaaS during your integration, to make sure UNIPaaS emails are disabled.