Notifications - Webhooks

This document will guide you on how to correctly integrate Webhooks Notifications within PowerBoard.

📘

Before you begin

When sending requests to PowerBoard’s API, you must provide either a Public Key and/or Secret Key depending on your use case.

API keys are generated via PowerBoard’s Merchant Dashboard, in three easy steps:

1. Login to the PowerBoard Merchant Dashboard.
2. Click on the ‘My Company’ link and proceed to the ‘API and Security’ heading.
3. On screen, you’ll see both Public and Secret Key required to send requests to PowerBoard’s API.

Your integration will utilise the following components:

• PowerBoard REST API

Overview

Use PowerBoards Notification service to get real-time updates on important events within your integration.

To enable webhook notifications, you will need to register a secure URL to the required events. PowerBoard will then send an automatic response to each
subscribed webhook notifying you when any of these events occur.

Including webhook's into your PowerBoard integration will allow you to get updates on newly created transactions, subscriptions, notifying you of an upcoming card expiry, etc.

❗️

PowerBoard requires all webhook URLs within the production environment to be secure via HTTPS.

Types of events

Below is a list of events that PowerBoard currently send.

Integration Steps

Steps to integrate notifications via Webhook

Step 1) Identify the required events for your integration.

You can find a list of them above.

Step 2) Create a webhook endpoint on your backend server

Create a webhook endpoint on your backend server and setup to receive the event notification.

Step 3) Register your webhook URL

Register your webhook URL by making a request to our notification's endpoint, registering your webhook URL to the required events.

See below example:

API Request details:

{
    "event": "transaction_success",
    "destination": "{{YOUR_WEBHOOK_URL}}",
    "type": "webhook",
    "transaction_only": true
}

{
    "status": 201,
    "error": null,
    "resource": {
        "type": "notification",
        "data": {
            "transaction_only": true,
            "_id": "64cafaf2dd42c226f9b6e0ce",
            "type": "webhook",
            "event": "transaction_success",
            "destination": "{{YOUR_WEBHOOK_URL}}",
            "created_at": "2023-08-03T00:55:14.657Z",
            "updated_at": "2023-08-03T00:55:14.657Z"
        }
    }
}

🚧

Ensure you are storing the Webhook ID i.e. resource.data._id returned in the response. You will be using it to updated/edit the webhook.

Step 4) Test your webhook notification

To ensure that it is receiving the correct response based on the subscribed event types. You can find steps to test your setup below.

Step 5) Deploy the webhook notification into your production environment.

You will need to setup the notification in our production environment as required.

Notification User Authentication

PowerBoards user authentication feature allows you to manage your accounts webhook security by supporting Basic authentication protocols for encoding webhook headers.

With user authentication enabled an authorisation, username, and password will be passed into the header of the webhook notification.

Steps to enable user authentication

Step 1) Login to the PowerBoard Merchant dashboard using your user login credentials

Step 2) Navigate to Notifications → User Auth → Add New

Step 3) Fill out the Label, Username, and Password fields with your required values.

Step 4) Configure your webhook with the newly created User Authentication, this can be done via the PowerBoard merchant dashboard.

Test your integration

Before going live with your webhook it is important to ensure it is working correctly and as expected. Follow the below steps to test and verify.

Step 1) Ensure the Notification setup steps are completed to correctly setup your PowerBoard webhook.

Step 2) Complete a transaction or event that will trigger the event you are Subscribed to.

Step 3) Verify your webhook endpoint is receiving the correct response with the expected data.

Example Webhook Response

{
  "event": "transaction_success",
  "data": {
    "_id": "64cafb7d61433926cd739445",
    "transaction": {
      "type": "sale",
      "status": "complete",
      "_source_ip_address": "140.168.135.2",
      "gateway_specific_code": null,
      "gateway_specific_description": null,
      "error_message": null,
      "error_code": null,
      "status_code": null,
      "status_code_description": null,
      "include_authorization": false,
      "_id": "64cafb7d61433926cd739446",
      "currency": "AUD",
      "amount": 59,
      "amount_fee": null,
      "amount_surcharge": null,
      "amount_original": null,
      "created_at": "2023-08-03T00:57:33.387Z",
      "external_id": "ed89987d-7e11-4d14-8dd8-6f48743307b1:f180a5b0-b282-419b-b40c-b890da66e4cf",
      "external_reference": "321500292640"
    }
  }
}

Notification logs

You can view a list of all notification logs sent by PowerBoard via API, if required. These can be filtered by date, type, event, etc.

See below example:

Unsubscribe to a notification

You can unsubscribe to a notification via our API or via the PowerBoard merchant dashboard.

Unsubscribe via API

Step 1) Identify the notification Events and ID’s you would like to unsubscribe to.

Step 2) Make a request to our DELETE notifications endpoint using the notification ID as a Path parameter.

See below example:

Step 3) Verify the event notification is longer being received by the registered destination.

Unsubscribe via the PowerBoard merchant dashboard

Step 1) Login to the PowerBoard merchant dashboard using your merchant user credentials.

Step 2) Using the left-hand side menu, navigate to the Notifications section.

Step 3) Identify the notification you would like to unsubscribe to. You can search through Notification or Event type via the Filters on the top of the page.

Step 4) On the notification you would like to delete. You will find an “Actions” button on the right-hand side of the page. Click this and select “Remove” from the dropdown.

Step 5) Verify the event is no longer triggering a notification to the registered email destination.