Welcome to UNIPaaS docs

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

  • onboarding/update
  • authorization/update
  • ewallet/create
  • payout/update
  • plan/create
  • plan/update
  • subscription/create
  • subscription/update
  • subscription/charge-success
  • subscription/charge-failure
  • notification/create

Rules

  • You can have multiple subscriptions per each webhook.
  • After 10 failed notifications you will receive an email warning you of the issue.
  • After 100 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 2 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 'https://sandbox.unipaas.com/platform/webhooks' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PLATFORM_SECRET_KEY>' \
  --data-raw '{
    "webhookName": "authorization/update",
    "email": "[email protected]",
    "url": "https://example.com/webhook" 
   }'

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

curl --request PATCH \
  --url 'https://sandbox.unipaas.com/platform/webhooks/{webhookId}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <PLATFORM_SECRET_KEY>' \
  --data-raw '{
    "url": "https://example.com/webhook-updated-url" 
   }'

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

curl --request DELETE \
  --url 'https://sandbox.unipaas.com/platform/webhooks/{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();

const SECRET = '<PLATFORM_SECRET_KEY>';

app.use(bodyParser.urlencoded({ extended: true }));
app.use(bodyParser.json());
app.use(bodyParser.raw());

app.post('/webhook', function (req, res) {
  const {headers, body} = req;
  const signedHeader = headers["x-hmac-sha256"];
  const hash = createHmac('sha256', SECRET)
    .update(JSON.stringify(body))
    .digest('hex');
  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')
})

app.listen(8080)

Onboarding

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

The body will include the onboardingResult object:

Parameter

Always Available

Type

Description

vendorId

Yes

String

Vendor unique identifier

vendorName

No

String

once your vendor has initiated the onboarding process and submitted the first form you will be able to see the vendor's name.

status

Yes

Enum

STARTED - This status indicates that a vendor have loaded the onboarding.

TYPE_CHANGE - This status indicates that a vendor have changed the onboarding type (individual / business).

ACCEPT_PAYMENTS_IN_REVIEW - This status indicates that a vendor finished the initial onboarding process and is now under review.

ACCEPT_PAYMENTS_SUCCESS - This status indicates that a vendor finished the initial onboarding process and can now accept payments.

ACCEPT_PAYOUT_IN_REVIEW - The Vendor has completed the entire onboarding process, and the application is being reviewed by UNIPaaS.

ACCEPT_PAYOUT - The Vendor has completed the entire onboarding process, the application was internally reviewed by UNIPaaS, and is now allowed to perform payouts.

DECLINED -
This status will appear for a vendor with a declined application. Applications can be declined for multiple compliance reasons.

completionRate

Yes

Number

Onboarding progress of your vendor, ranged between 0-100

Payin

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:

Parameter

Always Available

Type

Description

authorizatioId

Yes

String

Unique ID of the Object

authorizationStatus

Yes

Enum

The status of the Authorization. See below detailed information

paymentOptionResult

Yes

Enum

The payment Option details

currency

Yes

String

The Currency of the payment

amount

Yes

Number

The Amount of the payment

orderid

Yes

String

Unique ID form the merchant system

processor

Yes

Object

Additional data from the acquirer.

items

Yes

Object

The items of the order per item per vendor

transactionId

Yes

String

The transaction ID of the specific payment operation

eWallet

eWallet notifications are created to notify you when your vendor receives money for the first time - creating an automatic eWallet in the accepted currency. Each time an eWallet 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:

Parameter

Always Available

Type

Description

eWalletId

yes

string

eWallet unique identifier

vendorId

no

string

The unique ID of the vendor's eWallet.
If the eWallat is the platform ewallet it will return null

platformId

yes

string

Unique ID of the platform

currency

yes

enum

USD, GBP, EUR

Payouts

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:

Parameter

Always Available

Type

Description

payoutId

yes

string

status

yes

Enum

amount

yes

number

currency

yes

string

createdDate

yes

date

updatedDate

yes

date

targetReferenceId

no

string

Subscriptions

Subscription webhooks were created to notify about changes that happen regarding your plans or buyer subscriptions.

Plans Object
You will be notified when a new plan is created or updated

Available webhooks
plan/create , plan/update

The body will include the plans object:

Parameter

Always Available

Type

Description

action

Yes

plan/created
plan/updated

id

Yes

UUID

Unique plan ID

isActive

Yes

boolean

Defines if plan is active

isArchived

Yes

boolean

Defines if plan is archived

`modifiedOn

Yes

Timestamp

Time of last modification

createdOn

Yes

Timestamp

Time of creation

updatedBy

Yes

UUID

Updater Id

createdBy

Yes

UUID

Creator Id

name

Yes

String

Plan name

description

Plan Description

price

Yes

Integer

Plan price amount

Subscriptions object
You will be notified when a new subscription is created or updated, and when a subscription payment is charged or fails.

Available webhooks
subscription/create , subscription/update , subscription/charge-success, subscription/charge-failure

The body will include the subscriptions object:

Parameter

Always Available

Type

Description

action

Yes

subscription/create - notifies about all subscription creation events

subscription/updated - notifies about all changes that made to the subscription, as per the following:
subscription/renewed (Returns both new and old subscription object, and all bill items)
subscription/expired
subscription/paused
subscription/paymentOptionExpired

subscription/charged notifies about all charges that were made to subscriptions, as per the following:
subscription/charge-success
subscription/charge-failure

status

Yes

String

active - Subscription is active
trial - Subscription in trial period
paused - Subscription was paused
expired - Subscription has reached expiration date
cancelled - subscription was canceled

ID

Yes

String

Unique identifier

identifier

Yes

String

Used for grouping renewed subscriptions

startedOn

Yes

Timestamp

Indicates when the subscription was created

endsOn

Yes

Timestamp

Indicates when the subscription will expire (if applicable)

autoRenewal

Yes

Boolean

Indicates if the subscription will renew automatically after reaching expiration date

pausedAt

No

Timestamp

Indicates when the subscription was paused

nextBillingOn

No

Timestamp

Indicates when the next payment cycle billing is due (excluding retry billing)

trialStart

No

Timestamp

Trial period start date

strialEnd

No

Timestamp

Trial period end date

nextBillingRetryOn

No

Timestamp

Date and time of next billing retry event (excluding in-cycle billing)

isInBillingRetry

No

boolean

Indicated if the subscription is in billing retry mode

Notifications

Notification webhooks will help you trigger transactional emails to your vendors, they include a subject line and body text, which can be used in emails.

Available webhooks
notification/create

The following information is included in the webhook

Paremeter

Always available

Type

Description

vendorId

Yes

String

Identifies the vendor this notification is relevant for

subject

No

String

Includes notification email subject.

Example:
"Success! You can now payout your balance"

body

No

String

Includes notification email body.

Example:
"We are happy to inform you that your account is fully activated. You can now payout your balance."

🚧

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.

Updated 2 days ago

Platform Webhook Notifications


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.