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/chargeSuccess
  • subscription/chargeFailure
  • notification/create
  • ewalletTransaction/create
  • transfer/update

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

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

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:

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

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

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:

ParameterAlways AvailableTypeDescription
payoutIdyesstring
statusyesEnum
amountyesnumber
currencyyesstring
createdDateyesdate
updatedDateyesdate
targetReferenceIdnostring

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:

ParameterAlways AvailableTypeDescription
actionYesplan/created
plan/updated
idYesUUIDUnique plan ID
isActiveYesbooleanDefines if plan is active
isArchivedYesbooleanDefines if plan is archived
modifiedOnYesTimestampTime of last modification
createdOnYesTimestampTime of creation
updatedByYesUUIDUpdater Id
createdByYesUUIDCreator Id
nameYesStringPlan name
descriptionPlan Description
priceYesIntegerPlan 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:

ParameterAlways AvailableTypeDescription
actionYessubscription/create - notifies about all subscription creation events

subscription/updated - notifies about all changes 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
statusYesStringactive - Subscription is active
trial - Subscription in trial period
paused - Subscription was paused
expired - Subscription has reached expiration date
cancelled - subscription was cancelled
IDYesStringUnique identifier
identifierYesStringUsed for grouping renewed subscriptions
startedOnYesTimestampIndicates when the subscription was created
endsOnYesTimestampIndicates when the subscription will expire (if applicable)
autoRenewalYesBooleanIndicates if the subscription will renew automatically after reaching expiration date
pausedAtNoTimestampIndicates when the subscription was paused
nextBillingOnNoTimestampIndicates when the next payment cycle billing is due (excluding retry billing)
trialStartNoTimestampTrial period start date
trialEndNoTimestampTrial period end date
nextBillingRetryOnNoTimestampDate and time of next billing retry event (excluding in-cycle billing)
isInBillingRetryNobooleanIndicated if the subscription is in billing retry mode
authorizationIdNoUUIDRelated authorizationId.

Available only for actions: subscription/charge-success or subscription/charge-failure
transactionIdNoUUIDRelated transactionId.

Available only for actions: subscription/charge-success or subscription/charge-failure

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

ParemeterAlways availableTypeDescription
vendorIdYesStringIdentifies the vendor this notification is relevant for
subjectNoStringIncludes notification email subject.

Example:
"Success! You can now payout your balance"
bodyNoStringIncludes 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.