Shared Signals: An Open Standard for Webhooks

New OpenID Foundation draft enables secure and privacy protected webhooks to power an “API-First” world

Author: Atul Tulshibagwale


APIs are an increasingly important aspect of software today, and “API-First” is the mantra being followed in a lot of new software development. A critical aspect of efficient APIs is their ability to notify callers of changes relating to something the caller is interested in. Such mechanisms are often referred to as “Webhooks”, sometimes as “Callbacks”. Webhooks in most APIs are proprietary implementations, although API standards such as and Open API have specified mechanisms such as “Long Running Operations” and “Callbacks” respectively. In both these standards, the Webhook mechanism is specific to resources recently operated upon by the API client, and so is limited in its scope.

The Shared Signals and Events Framework

The OpenID Foundation formed the “Shared Signals and Events” (SSE) Working Group as a combination of the previous OpenID RISC working group and an informal industry group that was focused on standardizing Google’s CAEP proposal. These represented two distinct applications of the same underlying mechanism of managing asynchronous streams of events. Therefore the SSE Framework is now proposed to be a standard for managing such streams of events for any application, not just CAEP and RISC. In effect, it is a standard for generalized Webhooks.

The SSE Framework defines stream-based communication mechanisms between Transmitters that generate events and Receivers that consume them. It defines an Event Stream Management API for obtaining the Transmitter configuration: Which events it supports, how they can be verified, and where it sends them to the receiver. Note that since this call to get the Transmitter configuration can also be authorized using OAuth, a Transmitter may decide based on which Receiver is requesting the configuration, which events it would support for that Receiver. The Receiver can specify the URL at which it wishes to receive the events, and the types of events it is interested in receiving. It also provides mechanisms for adding or removing subjects about which events should be included in the stream, and for pausing, starting and stopping the stream. The actual events are delivered using Security Event Tokens (SETs), which are potentially signed JSON objects. The delivery mechanisms are defined using IETF draft specifications for SET Push or Poll.

In combination with OAuth, which can be used to authorize calls between the Receiver and the Transmitter, this SSE Framework provides a comprehensive mechanism for implementing secure, privacy protected webhooks.

How It Works

Many internet services today have a “multi-tenanted” architecture, which means that each service hosts a number of independent customers within their infrastructure. Using SSE, streams may be managed using host-level authorization or tenant level authorization. Using host-level authorization requires the Transmitter to trust the Receiver highly, such that intentional or unintentional action from the Receiver does not leak data about a tenant to the Receiver. For example, if a Receiver uses host-level authorization to enable the stream for a customer that hasn’t authorized it, the Receiver will start receiving events for the customer without their knowledge.

It is therefore safer to use tenant level authorization, where the tenant administrator can authorize such management actions. This method is described below:

Setting up a Stream

The following example describes how an administrator authorization may be used to start a stream:


Adding a Subject

A Subject Principal in SSE can be a user, device, application or even a session. A subject can also be an aggregate subject like an OU, group or tenant. A Receiver can explicitly add or remove subjects in a stream. A stream will contain events only about subjects that are explicitly or implicitly included in the stream. In some cases, it makes sense to implicitly include all applicable subjects to a stream (for example, if events being exchanged are about the security of the subject). In other cases, a subject may explicitly authorize the use of their information in a stream, providing privacy protection (for example, if a user’s location needs to be shared). In the explicit case, the following steps can be taken to authorize the inclusion of events regarding a user subject in the stream:


Removing a Subject

The SSE Event Stream Management API also supports removing subjects, whether or not they were explicitly added. The flow to remove a subject is the same as the “add subject” flow described above.

Other Features

The SSE Framework also defines ways for both Receivers and Transmitters to enable, disable and pause streams. It also defines a mechanism for Receivers to verify the stream is active, which could be used as a “heartbeat” mechanism.

Current Status and Call to Action

The SSE Framework draft has been adopted as an Implementer’s Draft by the OpenID Foundation. This is a great time to begin implementations based on this specification. In your APIs, consider adding the webhook capability using the SSE Framework instead of a proprietary way of providing such functionality.

For more information, please visit the Shared Signal & Event Working Group page.