Introduction to Webhooks

Webhooks is a comprehensive service designed to facilitate real-time event subscription and notification delivery.

You can utilise its REST API to create and update webhook endpoints, and specifying desired events for notification for the endpoints. Additionally, clients can retrieve historical or missed events on demand, update their details, and manage event subscriptions. Webhooks provide a robust platform for efficient event-driven interactions, retrieving notification details, subscribing to events, and re-sending notifications.

The advantage of webhooks is that there is no persistent open connection to the system where you need to keep filtering for events that you are interested in. It is an asynchronous mechanism where you wait for the system to notify you. The HTTP payload will contain the details of the event.

Before using webhooks, you will need to setup a URL that can listen for any alerts. Contact the Thredd Application Support Team for help with this as your IP address must be whitelisted first. When the URL has been set up correctly, it must be registered using the Create Webhook endpoint.

📘

Note

We recommend when implementing handling of webhooks to utilise a JSON parser. This is to ensure as we add new functionality to our webhooks that your system does not start to fail the processing of the webhooks.

About Events

When a webhook has been created, events can be created for them. An event is an activity that happens outside of your system, such as a card transaction or card being blocked. For example, a fraud event is triggered which causes the card to be suspended. The webhook is then sent the details of the attempted transaction, allowing you to proactively contact your cardholder.

The currently supported events are described in the following table.

How it Works

1. Program managers create a webhook using the Create Webhook endpoint.
2. The program manager creates a subscription for the webhook to subscribe to specific events using the Add Event Subscriptions endpoint. This allows the webhook to receive notifications for those events.
3. When the setup is complete, whenever the event triggers, the webhook sends notifications to the program managers, ensuring they receive updates on relevant events and changes on their systems or applications.

Responding to Webhooks

Webhook endpoints should return a 2XX HTTP status code. Any other information you return in the request headers or request body will be ignored. If Thredd does not receive a 2XX response to our POST request, we will retry the request to a maximum of 3 times.

Thredd will not process the event further after 3 retries. We recommend utilising notificationId as your main duplicate check. This is important if a webhook has failed and needs to be resent.

Available Webhook Endpoints

The following table describes each of the available endpoints you can use for creating and maintaining webhooks and events.