What is a Webhook?

Briefly, we can say that a webhook is the notification of an event that has occurred somewhere, and that is sent to a listening application that is interested in such event.

The Event Model

If we consider the overall model of processes, where an activity is performed, and eventually preceding other activities, until a final result, we can define the events as the triggers of such activities (eg. something has occurred, and therefore we must perform some subsequent activities).

Equally we can consider that some activities produce the information that an event has occurred, to make aware interested actors to react (eg. while performing this activity, this has happened: feel free to act consequentially).

If you think about it, this happens in your daily life as well:

• Today I woke up and I brushed my teeth - You are informing the listener that two events occurred today: you (the actor) woke up and you brushed your teeth

• While I was crossing the street, a car horned at me - You are informing the listener that a car (the actor) horned at you

Standard Models

Academic studies have analyzed this concept more than a century ago, and some formal representations of such concepts have been designed and adopted by the Information Technology industry as standards (eg. BPMN, Workflows, etc.), in order to rationalize and optimize processes within the information systems (although, not all activities are actually performed by systems: some actors in such processeses are humans, and such scenarios we talk about manual events).

For example, one of the most common of these formal models, the Business Process Management Notation (BPMN), that defines several types:

• Triggers - Those who start a process or an activity(like a message or a timer),

• Intermediate Events - Those produced during an activity of a process

• Terminal Events - Those that cause the end of the process

Event-Driven Design

The development and operational model of systems has greatly benefit by the adoption of designs where those systems were loosely coupled with other systems, implementing asynchronous operations based on the occurrence of events produced elsewhere: this approach, that today seems a given for many developers, has optimized the overall performances and maintainability of services, which are able to isolate their functions, and instead of pulling the event at regular intervals (eg. querying an external service every X minutes to see if anything has happened), can be resiliently listening and reacting only when needed.

This design has also produced extensibility opportunities, since it made it possible for a system to be more easily integrated (once the events and their information is known), since the dependency from the components is not direct and the load is moved to the transportation medium, rather than being provided by the service itself (eg. the I/O to the databases is reduced or removed, since the event carrying all needed information has been produced).

The Webhook Model

Moving out of the conceptual model, the initial problem faced to export events out of the boundaries of the systems of a service provider to external listening applications consisted in the format and protocol of the transportation.

The best solution found along the way (and at today still the most used) to notify such events is through HTTP callbacks: a POST request through the HTTP protocol to a publicly exposed end-point belonging to an application accepting such notifications.

This methodology has been commonly denominated by the industry as Webhook.

At today, there is still no agreed common protocol to define the format and contents of a Webhook, although some elements represent a pattern across the various implementations available:

• The callback request is performed using the POST verb of the HTTP protocol

• The payload (the content) of the request is formatted as a JSON or XML text (although some implementations use the www-form-urlencoded format)

• The request optionally includes an header or a query string element that expresses a signature that is interpretable by the subscribing application (to be sure of the genuinity of the information)

CloudEvents

In the last years, the Cloud Native Computing Foundation (CNCF) has been working on a standardization of the Webhook model, and has produced the CloudEvents specification, that defines a common format for the payload of the Webhook requests, and a set of extensions that can be used to enrich the information carried by the event.

The CloudEvents specification is still in its early stages, and it is not yet widely adopted by the industry, but it is a good starting point to define a common model for the Webhook events.