webhooks: APIs and REST
Webhooks are a technique within the domain of APIs, particularly in combination with REST, that allows systems to communicate more efficiently than through traditional polling. Instead of a client continuously asking whether new data is available — a process called polling — a webhook reverses the direction of communication: the server automatically sends a message to the client as soon as a certain event occurs. This model is also called 'event-driven'. It is a powerful pattern that is applied in many modern API architectures, especially when timeliness and efficiency are important.
The webhook pattern was proposed in 2006 by Jeff Lindsay. He introduced the idea as a way to use APIs without systems having to constantly check whether there is something new. This was a response to the inefficiency of polling, in which a client regularly calls a server to ask whether there are changes, even though often nothing happens. With webhooks, that wrong approach is avoided: data is only sent when an event actually takes place. It is a smart solution that reduces bandwidth, server load and latency.
A webhook works as an HTTP callback. This means that a producer — for example an API server — sends an HTTP POST request to a pre-specified URL of a consumer as soon as an event occurs. That URL is usually an endpoint that the receiver has set up itself. The data that is included in the POST request, also called the payload, contains information about what has happened. The consumer can then take action based on that information, such as updating a database, starting a build process or sending a notification.
According to the Dutch government site developer.overheid.nl, webhooks count as the most important event-driven pattern within the Dutch API strategy. This shows that the government takes this model seriously as part of modern, efficient digital service provision. By using webhooks, government services can respond more quickly to changes in systems, without having to continuously perform checks. It promotes interoperability and reduces the load on systems, which is crucial at large scale.
A well-known example of the use of webhooks is GitHub. GitHub describes repository webhooks as a mechanism in which a server receives HTTP POST payloads when certain events occur in a repository. Think of pushing code, opening a pull request or creating a new release. Developers can set up a webhook that automatically starts a build in a CI/CD pipeline as soon as code is pushed. This makes it possible to set up continuous integration and continuous delivery in an automated way, without anyone having to intervene manually.
GitHub's REST API documentation on webhooks was published in 2019. The page on repository webhooks dates from 3 June 2019. This shows that webhooks have now become a fixed part of modern API documentation. The descriptions are detailed and provide developers with clarity about which events are available, what the payloads look like and how the webhooks can be managed via the API. This kind of documentation is essential for the adoption and correct application of the pattern.
Webhooks are also included in specifications that standardize APIs. For example, OpenAPI 3.0.0 gained support for callbacks in December 2017, which forms the basis for describing webhooks in API specifications. However, it was only in OpenAPI 3.1, which appeared in 2021, that support for webhooks was fully worked out. This means that since then developers can explicitly indicate in their API specification which endpoints can be used as webhooks, which makes development and integration easier.
Another important specification is the CloudEvents HTTP webhook specification. This specification, which in the repository dates from 9 December 2017 and mentions version 1.0.3-wip, tries to bring standardization to the way events are sent via HTTP. CloudEvents is an initiative to create a common format for describing events in cloud-native applications. By using CloudEvents, systems from different vendors can communicate better with each other, including when they use webhooks. It prevents each party from using its own, unclear format for the payload.
Security is an important aspect when using webhooks. Because a webhook allows an external system to send an HTTP request to your server, it is essential to check whether the call actually comes from the expected source. A commonly used method is signing the HTTP requests. In this, the sender adds a digital signature to the request, which the receiver can verify. RFC 9421, which was completed in 2024, describes a standard for signing HTTP requests. This RFC is mentioned in later webhook documentation as a possible solution to guarantee the authenticity and integrity of webhook calls. It offers a secure and interoperable way to prevent unauthorized parties from sending false events.
Webhooks fit well within the broader context of REST architecture. REST, or Representational State Transfer, is a style of software architecture for designing network topologies, especially for web services. REST APIs use HTTP methods such as GET, POST, PUT and DELETE to manipulate resources. Webhooks extend this approach by allowing servers to actively communicate with clients, instead of clients having to passively wait for changes. Although REST itself is initially based on polling, webhooks complement this with a push mechanism that better suits real-time applications.
Yet webhooks are not a replacement for REST, but a supplement. A typical integration uses both REST and webhooks: REST for retrieving and managing resources, and webhooks for receiving notifications about changes. For example: an application can retrieve a list of users via a REST call, but uses a webhook to know immediately when a new user is created. This ensures a reactive and efficient architecture.
A disadvantage of webhooks is that they depend on the availability of the consumer. If the receiver is offline when an event occurs, the webhook notification can be lost. That is why it is important to build in error handling, such as retry mechanisms or storing events in a queue. In addition, the consumer must be set up securely, because an open webhook endpoint can be an attack vector. Think of DDOS attacks, injection or unauthorized access.
Despite these challenges, webhooks have grown into a standard part of modern API ecosystems. They are used in countless services, from GitHub and GitLab to Stripe, Slack and AWS. The combination of simplicity, efficiency and real-time communication makes it a powerful tool for systems that need to respond quickly to changes. With standardization via OpenAPI, CloudEvents and RFC 9421, the technology is becoming increasingly reliable and secure.
In summary: webhooks are an event-driven approach within APIs, especially in combination with REST, in which a server automatically sends a POST request to a client when an event occurs. The idea was introduced in 2006 by Jeff Lindsay as an alternative to polling. It is widely used, including by GitHub and the Dutch government, and is standardized in specifications such as OpenAPI 3.1, CloudEvents and RFC 9421. Although there are security and reliability issues, webhooks form an essential building block of modern, reactive systems.