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.

Common uses of this capability might include the following uses.
  • 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.

An interest consists of two fields, a friendly 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 the data object of an event. When it references the data 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 or excluded.
For example, in a scenario when authentication events are the key interest and you want to filter out authentications that occur through federation, use these clauses.
  • 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

The id 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.

You can trigger dead-letter reconciliation in either of two ways:
  • 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.
A status API can be used to check whether a webhook is running a reconciliation and the current progress of the reconciliation. See the API documentation for details. Only the result of the execution of reconciliation is kept per webhook. These results are kept for 7 days or until another reconciliation is run.

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.