Webhook Subscription

MBanq Cloud Webhooks Tutorial

Webhooks are a mechanism that alerts you when something occurs that you are interested in. Instead of having your code sit by and wait for an event to happen or complete, a webhook can alert your code when the event actually happens. Webhooks do this by firing HTTP request on the occurence of event. Webhooks are an essential feature of the MBanq Cloud platform, allowing you to receive real-time notifications and updates about various events. You can configure webhooks to subscribe to specific events and receive payloads containing relevant data. This tutorial will guide you through the functionality of webhooks and provide examples of creating subscriptions and retrieving supported events.

An entity is an Mbanq object or process resource that can trigger actions (events) such as CREATE, DELETE, and UPDATE.

In order for Mbanq to send webhook payloads, your server needs to be accessible from the Internet. Mbanq will send along a few HTTP headers and JSON payload to differentiate between event types.

Header signature - generated by using HMAC-SHA512 with your secret key during endpoint creation and used to verify the authenticity of the request.

There are two steps to get updates about any action on an entity:

1. Registering a subscriber
2. Registering a subscription

Registering a Subscriber

There are three types of subscribers:

1. WEBHOOK:
   This option allows you to specify a URL endpoint where the event will be triggered. This is useful if you want to integrate the notifications with your own system.
   The CURL request to register a WEBHOOK type subscriber is given below. In this request, the target specifies the destination of the webhook call along with the headers.
   cURL

   curl --location 'https://api.cloud.mbanq.com/v1/subscribers' \
   --header 'authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsImlzQWNjZXNzVG9rZW4iOnRydWUsImV4cCI6MTY5MTA4MTMzOSwidXNlcklkIjoxLCJpYXQiOjE2OTEwNzc3Mzl9.hSOuDnUk8Hv4VZ3LYrWOYN44xBEAhiwoCuEoPA0THBR2UVlFJ9TiNSODmGTfhd-sUJ-Zqk8fniuNzTIRVhhXGA' \
   --header 'content-type: application/json' \
   --header 'tenantid: z01h421j7xqf7h31wgkm7yy1gw' \
   --data '{
     "name": "Web hook notification",
     "type": "WEBHOOK",
     "target": "https://webhook.com",
     "deliveryRetryLimit": 3,
     "active": true,
     "secretKey": "123456",
     "headers": [
       {
         "name": "n1",
         "value": "v1"
       },
       {
         "name": "n2",
         "value": "v2"
       }
     ]
   }'
   

2. EMAIL:
   This option allows you to specify an email address where the events will be sent. This is useful if you want to receive the notifications to initiate a manual action taken by a person.
   The CURL request to register a EMAIL type subscriber is given below. To send notifications to a specific email address, the email parameter must be passed in this request.
   cURL

   curl --location 'https://api.cloud.mbanq.com/v1/subscribers' \
   --header 'authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsImlzQWNjZXNzVG9rZW4iOnRydWUsImV4cCI6MTY5MTA4MTMzOSwidXNlcklkIjoxLCJpYXQiOjE2OTEwNzc3Mzl9.hSOuDnUk8Hv4VZ3LYrWOYN44xBEAhiwoCuEoPA0THBR2UVlFJ9TiNSODmGTfhd-sUJ-Zqk8fniuNzTIRVhhXGA' \
   --header 'content-type: application/json' \
   --header 'tenantid: z01h421j7xqf7h31wgkm7yy1gw' \
   --data '{
     "name": "Send email to the client",
     "type": "CLIENT_EMAIL",
     "deliveryRetryLimit": 3,
     "active": true
   }'
   

The response of these requests returns the ID of the subscriber through which one can create subscriptions.

Creating a Subscription

To create a subscription for a webhook, you need to specify the entity and action for which you want to receive notifications. The following examples demonstrate how to create subscriptions for different types of subscribers: WEBHOOK, EMAIL, and CLIENT_EMAIL.

Create a subscription for a WEBHOOK subscriber:

curl --location 'https://api.cloud.mbanq.com/v1/subscriptions' \
--header 'authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsImlzQWNjZXNzVG9rZW4iOnRydWUsImV4cCI6MTY5MTA4MTMzOSwidXNlcklkIjoxLCJpYXQiOjE2OTEwNzc3Mzl9.hSOuDnUk8Hv4VZ3LYrWOYN44xBEAhiwoCuEoPA0THBR2UVlFJ9TiNSODmGTfhd-sUJ-Zqk8fniuNzTIRVhhXGA' \
--header 'content-type: application/json' \
--header 'tenantid: z01h421j7xqf7h31wgkm7yy1gw' \
--data '{
  "subscriberId": 1,
  "entity": "CLIENT",
  "action": "CREATE"
}'

Similarly, we can pass the subscriber id for EMAIL and CLIENT_EMAIL and subscribe for the events.

Deleting a Subscription

If you want to stop receiving notifications for a specific subscription, you can delete it using the following API:

DELETE https://api.cloud.mbanq.com/v1/subscriptions/{id}

Supported Events

You can retrieve the list of supported events for different types of subscribers. The examples below demonstrate how to retrieve the supported events for WEBHOOK, CLIENT_EMAIL and EMAIL.

• Retrieve supported events for WEBHOOK:

GET https://api.cloud.mbanq.com/v1/subscriptions/events?type=WEBHOOK

• Retrieve supported events for EMAIL:

GET https://api.cloud.mbanq.com/v1/subscriptions/events?type=EMAIL

The responses for each request will provide a list of entities and their corresponding actions that can be subscribed to for receiving notifications. Below is an example of the response structure:

[
  {
    "entity": "PRODUCTMIX",
    "actions": [
      "CREATE",
      "DELETE",
      "UPDATE"
    ]
  },
  {
    "entity": "FUND",
    "actions": [
      "CREATE",
      "UPDATE"
    ]
  },
  {
    "entity": "SHAREACCOUNT",
    "actions": [
      "ACTIVATE",
      "APPLYADDITIONALSHARES",
      "APPROVEADDITIONALSHARES",
      "APPROVE",
      "CLOSE",
      "CREATE",
      "REDEEMSHARES",
      "REJECTADDITIONALSHARES",
      "REJECT",
      "UNDOAPPROVAL",
      "UPDATE"
    ]
  }
]

This table outlines the parameters used in the code snippets:

By utilizing the MBanq Cloud API's webhook functionality and managing subscriptions, you can ensure that your system stays up-to-date with relevant events and receive timely notifications for processing data effectively.

Use Cases:

Debit card usage notifications

When a debit card is used, a card authorization request is generated. When a request is received to create a card authorization request, a notification is triggered to all subscribers to notify them of this event. To receive notifications, one must first register as a subscriber.

In this example, we assume that the notification type is a webhook. Therefore, a webhook will be triggered for every debit card transaction, with the necessary payload. The client can consume these details and take appropriate action.

To create a webhook subscription for card authorization events, follow these steps:

1. Register as a webhook subscriber as described in the steps above : Registering a Subscriber
2. Retrieve all the supported events for the webhook subscriber as described in the steps above : Supported Events and choose a appropiate entity and action. In the case of card authorization, entity is CARDAUTHORIZATION and action is CREATE
3. Create a subscription for the card authorization events as follows:
   cURL

   curl --location 'https://api.cloud.mbanq.com/v1/subscriptions' \
   --header 'authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsImlzQWNjZXNzVG9rZW4iOnRydWUsImV4cCI6MTY5MTA4MTMzOSwidXNlcklkIjoxLCJpYXQiOjE2OTEwNzc3Mzl9.hSOuDnUk8Hv4VZ3LYrWOYN44xBEAhiwoCuEoPA0THBR2UVlFJ9TiNSODmGTfhd-sUJ-Zqk8fniuNzTIRVhhXGA' \
   --header 'content-type: application/json' \
   --header 'tenantid: z01h421j7xqf7h31wgkm7yy1gw' \
   --data '{
     "subscriberId": 1,
     "entity": "CARDAUTHORIZATION",
     "action": "CREATE"
   }'