Notification webhooks
Notification webhooks are a highly versatile capability in IBM® Security Verify. They allow an administrator to set up an endpoint to receive a selected set of event data in real time. Any event that is raised in Verify can be propagated out to the configured webhook, which allows Verify to interact with external systems in an event driven manner.
- Tracking login attempts on a user
- Keeping an external CRM or User directory up to date with changes in Cloud Directory
- Detecting new MFA devices
- Forwarding events to a SIEM
For information about event payloads, see Event types and payloads.
The administrator can configure a notification webhook with a set of interests. This set of interests decides which events are sent from Verify to the external system.
Notification webhooks are high volume. When under load, Verify publishes a many events. The external system must be prepared to receive a matching level of load. Fast response times from the administrator-configured webhook endpoints are essential when notification webhooks are used in user flows.
Configuring
See the API documentation for the full webhook configuration object structure. This section focuses on the interests portion of a notification webhook.
The webhook configuration JSON file contains a notification
property. This
property is a nested JSON object that contains all of the notification-specific configuration
options. The interests
property is defined within this
notification
object. When an event is raised, it is checked against each element in
the interests
property. If any element within the interests
property evaluates to a match, the event is sent to the webhook destination. Interests are checked
in order, so in high-performance use cases, putting the broadest match first is the most efficient
method.
name
and a list of
clauses
. These clauses decide whether the interest is a match. The
clauses
are joined with an AND operation, and only if they all match is the
interest satisfied. A clause consists of three fields:key
- Is used to determine where in the event to inspect to discover whether this clause matches. It
must be a JSON property name.
key
can be used to evaluate top-level keys or keys within thedata
object of an event. When it references thedata
object, JSON dot notation is used. For example,data.action
. value
Value
is the expected value of the field that is being inspected.operation
- Indicates whether a match on this clause causes the event to be
included
orexcluded
.
-
Key:
event_type
, Value:authentication
, Operation:include
-
Key:
data.subtype
, Value:federation
, Operation:exclude
These clauses become the logical evaluation.
event_type
IS
authentication
AND
data.subtype
IS NOT
federation
Examples
The following code is a complete example of the notification
property within a
webhook configuration to fulfill various scenarios.
- All nonfederation authentication events
-
"notifications": { "interests": [ { "name": "Non-federation authentication events", "clauses": [ { "key": "event_type", "value": "authentication", "operation": "include" }, { "key": "data.subtype", "value": "federation", "operation": "exclude" } ] } ] }
Replay detection
Theid
field of an event remains consistent
for the lifetime of that event. Whether it be in a webhook callout, or in the event data that is
retrieved from the events API. This id
value is also used as the value in the
X-Webhook-ID
header for notification webhooks.Notification dead letters
You can configure a webhook to record when a notification was not successfully delivered to the webhook.
An administrator can reconcile the failed deliveries by using the dead letters API of the notification webhook, along with the events API. These recorded dead letters contain the ID of the undelivered notification and the time of the notification. To view the undelivered notification, an administrator can use the ID value to query the events API for a single event value directly. The timestamps of multiple events can be used to retrieve a range of events and then use the IDs to filter them on the client.
Dead letter reconciliation
An automated mechanism exists that attempts redelivery of dead letters to the configured webhook.
These reconciliation attempts are identifiable by the presence of the value "deadletter":
true
in the payload.
- Manually, by a call to the flush API.
- Automatically, when a notification webhook is showing a good health status.
- Set the configuration to specify how often this automated reconciliation occurs. See the API documentation for details.
- The manual API can still be used to trigger a reconciliation regardless of the configuration.
If an attempt at redelivery of a notification fails during reconciliation, then the reconciliation is ended. The hard time limit on reconciliations is 2 hours. If all dead letters are not flushed within that time, more reconciliations must be run.