Introduction:
IBM Security Verify (ISV) allows administrators to configure notification Webhooks to listen for and deliver events to end points. These end points are typically hosted on an external network and it is very much possible that the end points can go offline either during planned maintenance or unplanned outages. In such scenarios, what happens to the events that could not be delivered and how can applications that rely on the delivery of events implement a fault tolerant solution.
IBM Security Verify Webhooks provides manual and automated ways to reconcile failed event deliveries.
Configuring Notification Webhooks:
In the ISV administration Webhooks, navigate to Integrations -> Notifications webhooks. For more details, refer to the documentation.
An administrator has the option to add conditions that determine if a given ISV event should be included or excluded. For example, to include all events generated for a tenant, use tenantname as the Event key property and Field value as the name of the tenant as shown.
Automatic reconciliation:
Configure Notification Webhooks to record failures in event delivery in the internal ISV Webhooks database via the Administration console by navigating to Integrations -> Notifications webhooks. The reconcile time intervals can also be set. Currently the available time intervals are 5, 15 and 30 minutes. Event entries older than 90 days are automatically deleted from the internal database.
Manual reconciliation:
ISV Notification Webhooks also allows via APIs, manual reconciliation of events that did not get delivered successfully. These APIs are very useful in scenarios where reconciliation is part of an automated work flow.
The steps involved are:
- Fetch the event count
- List all the failed event record entries (optional)
- Trigger event reconciliation
- Check the status of event reconciliation
Event Count:
Allows an ISV administrator to query for existence of failed event delivery records.
Request (HTTP GET):
curl --location 'https://<tenant_url>/config/v1.0/webhooks/<webhooks_id>/deadletters/count' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'
- tenant_url = the URL of the tenant
- access_token = API access token
- webhook_id = the id of the webhook
Response:
{
"webhookId": "<webhook_id>",
"count": 1
}
where
- webhook_id = the id of the webhook
- count = number of events
List all failed events:
If there are failed events, the APIs allow an ISV administrator to list all the failed event records
Request: (HTTP GET)
curl --location 'https://<tenant_url>/config/v1.0/webhooks/<webhooks_id>/deadletters' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'
where
- tenant_url = the URL of the tenant
- access_token = API access token
- webhook_id = the id of the webhook
Response:
{
"webhookId":"<webhooks_id>",
"events":[
{
"id":"<event_id>",
"time":1698648323691
}
],
"count":1
}
where
- webhook_id = the id of the webhook
- event_id = Id of the event that failed delivery
- time = event creation unix timestamp in milliseconds
Trigger event reconciliation:
An ISV administrator can manually trigger reconciliation of all failed events
Request: (HTTP POST)
curl --location 'https://<tenant_id>/config/v1.0/webhooks/<webhooks_id>/deadletters/flush' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
"from": "2023-10-18T04:48:54.000Z",
"limit": 25,
"to": "2023-12-22T04:48:54.000Z"
}'
where
- tenant_url = the URL of the tenant
- access_token = API access token
- webhook_id = the id of the webhook
- from = ISO 8601 format time from which failed events are to be reconciled
- limit = the number of failed events to reconcile at a time
- to = ISO 8601 format time to which failed events are to be reconciled
Response:
204 - No content
Status of reconciliation:
An ISV administrator can check the status of the reconciliation process:
Request: (HTTP GET)
curl --location 'https://<tenant_id>/config/v1.0/webhooks/<webhooks_id>/deadletters/flush' \
--header 'Authorization: Bearer <access_token>' \
--header 'Accept: application/json'
where
- tenant_url = the URL of the tenant
- access_token = API access token
- webhook_id = the id of the webhook
Response:
{
"status": "complete",
"runtime": "1.91025836s",
"actioned": 1,
"started": "2023-11-20T05:28:17.35169066Z",
"finished": "2023-11-20T05:28:19.261949352Z",
"arguments": {
"from": "2023-10-18T04:48:54Z",
"limit": 1,
"to": "2023-12-22T04:48:54Z"
}
}
where
- actioned = the number of failed event deliveries that were successfully reconciled.
Conclusion:
ISV Notification webhooks provide an assured delivery mechanism for failed event deliveries that can be delivered automatically or manually via APIs as the situation demands.