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 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 '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:

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:

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:

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:

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:

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

🚧

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.