Introduction to Webhooks
Important
Webhooks functionality is currently in beta.
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.
| Event Code | Description |
|---|---|
| 101 | Supports when a fraud rule is triggered by a transaction. |
| 102 | Supports when a fraud alert is closed, either from your confirmation using the API, or 3 days after the alert was triggered. |
How it Works
- Program managers create a webhook using the Create Webhook endpoint.
- 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.
- 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.
| Retry | Time after first failure |
|---|---|
| 1st Retry | 1 second |
| 2nd Retry | 1 second |
| 3rd Retry | 1 second. |
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.
| Name | Verb | Endpoint | Description |
|---|---|---|---|
| Register New Webhook | POST | api/v1/Webhooks | Enables you to create a webhook service. It returns a Webhook identifier that should be saved if the notification needs to be amended in the future. |
| List Webhooks for Program Manager | GET | api/v1/Webhooks | Enables you to view all webhooks associated with a specific program manager. |
| Update Webhook Details | PUT | api/v1/Webhooks/{webhook_id} | Enables you to update webhook details by specifying the webhookId in the endpoint URL. |
| Get Webhook Details | GET | api/v1/Webhooks/{webhook_id} | Enables you to retrieve webhook details by using the webhookId in the endpoint URL. |
| Update Webhook Details | PUT | api/v1/Webhooks/{webhook_id}/status | Enables you to update the webhook status, such as activation and unregistration, by specifying the webhookId in the endpoint URL. |
| Get Webhook Heartbeat | GET | api/v1/Webhooks/{webhook_id}/heartbeat | Enables you to verify the status of their registered URL. |
| Add Event Subscriptions to Webhook | PUT | api/v1/Webhooks/{webhook_id}/subscriptions | Enables you to add subscriptions to existing events for a webhook. |
| Get Event Subscriptions for Webhook | GET | api/v1/Webhooks/{webhook_id}/subscriptions | Enables you to retrieve events subscribed to an endpoint. |
| Delete Subscriptions for Webhook | DELETE | api/v1/Webhooks/{webhook_id}/subscriptions/{event_code} | Enables you to remove an event subscription from a webhook by specifying the webhookId and event_code in the endpoint URL. |
Updated about 1 month ago