Webhooks

Introduction

Webhooks are a way for Basiq to notify your application when certain events occur in our system. This allows your application to react in real-time to changes in our solution without needing to constantly poll our APIs for updates.

Getting Started

To use webhooks, you will need to create a webhook endpoint in your application that can receive HTTP POST requests. When an event occurs in our system that you have subscribed to, we will send an HTTP POST request to your webhook endpoint with information about the event.

To create a webhook endpoint, you can use any web framework or platform that can receive HTTP POST requests. You will need to make sure that your endpoint is secure and can handle incoming requests in a timely manner.

Subscribing to Webhook Events

To subscribe to webhook events, you will need to create a webhook subscription in our system. You can do this by sending a POST request to the /notifications/webhooks endpoint with the following information:

URL: The URL of your webhook endpoint
Events: The types of events you want to receive notifications for

Once you have created a webhook subscription, we will send HTTP POST requests to your webhook endpoint whenever an event of the subscribed type occurs in our system.

Webhook Events

Our system supports several types of webhook events that you can subscribe to. These events relate to changes in users, consentsto name a few. To view the list of supported webhook events, you can send a GET request to the /events/types endpoint.

Handling Webhook Requests

When our system sends a webhook request to your endpoint, it will include a JSON payload with information about the event. You will need to parse this payload and handle it appropriately in your application.

The payload will include information such as the event type, the ID of the affected object in our system, and any additional data related to the event.

Managing Webhook Subscriptions

To manage your webhook subscriptions, you can send requests to the /notifications/webhooks endpoint. You can use the following methods to manage your subscriptions:

GET: Retrieve a list of your current webhook subscriptions
POST: Create a new webhook subscription

You can also send requests to the /notifications/webhooks/{webhookId} endpoint to manage a specific webhook subscription. This endpoint supports the following methods:

GET: Retrieve information about a specific webhook subscription
POST: Update the details of a specific webhook subscription
DELETE: Delete a specific webhook subscription

Webhook Messages

When a webhook is triggered for a certain event we will send you message. You can query and retrieve these messages by calling the APIs through the url:

GET /notifications/webhooks/{webhookId}/messages/: Retrieve a list of your current webhook messages
GET /notifications/webhooks/{webhookId}/messages/{messageId}: Retrieve a specific webhook message

An example of a webhook messages is shown below for the event user.created:

{
    "eventTypeId": "user.created",
    "eventId": "44a85f64-5717-4562-b3fc-2c963f66af44",
    "links": {
      "event": "https://au-api.basiq.io/events/44a85f64-5717-4562-b3fc-2c963f66af44",
      "eventEntity": "https://au-api.basiq.io/users/88a85f64-5717-4562-b3fc-2c963f66af88"
    }
}

Testing Webhooks

To test your webhook endpoint, you can send a test webhook request by sending a POST request to the /notifications/messages/test endpoint with the following information:

URL: The URL of your webhook endpoint
Events: The types of events you want to test
This will send a test webhook request to your endpoint with sample data for the selected event types.

📘

Webhooks

Sometimes, when you subscribe to a Webhook, it's necessary to wait for a cool-off period of up to 15 minutes. So please be patient during this time, if you still have issues, please reach out to [email protected].

Conclusion

Webhooks are a powerful way to keep your application in sync with changes in our system. By following this guide, you can create a secure and reliable webhook endpoint that can handle real-time updates from our system. If you have any questions or issues, please refer to our API documentation or contact our support team for assistance.