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.

Event CodeDescription
101Supports when a fraud rule is triggered by a transaction.
102Supports when a fraud alert is closed, either from your confirmation using the API, or 3 days after the alert was triggered.
103Supports notifying a customer when a card status changes. This event code will also send an EMV chip block script when an irreversible card status is set.

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.

RetryTime after first failure
1st Retry1 second
2nd Retry1 second
3rd Retry1 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.

NameVerbEndpointDescription
Register New WebhookPOSTapi/v1/WebhooksEnables 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 ManagerGETapi/v1/WebhooksEnables you to view all webhooks associated with a specific program manager.
Update Webhook DetailsPUTapi/v1/Webhooks/{webhook_id}Enables you to update webhook details by specifying the webhookId in the endpoint URL.
Get Webhook DetailsGETapi/v1/Webhooks/{webhook_id}Enables you to retrieve webhook details by using the webhookId in the endpoint URL.
Update Webhook DetailsPUTapi/v1/Webhooks/{webhook_id}/statusEnables you to update the webhook status, such as activation and unregistration, by specifying the webhookId in the endpoint URL.
Get Webhook HeartbeatGETapi/v1/Webhooks/{webhook_id}/heartbeatEnables you to verify the status of their registered URL.
Add Event Subscriptions to WebhookPUTapi/v1/Webhooks/{webhook_id}/subscriptionsEnables you to add subscriptions to existing events for a webhook.
Get Event Subscriptions for WebhookGETapi/v1/Webhooks/{webhook_id}/subscriptionsEnables you to retrieve events subscribed to an endpoint.
Delete Subscriptions for WebhookDELETEapi/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.