The ever-evolving landscape of modern applications & the need for organizations to have real time visibility of their infrastructure has resulted in the birth of a special technology called “Webhooks”. Unlike traditional APIs where one system actively polls another for information, Webhooks allow systems to push data to each other whenever an event occurs thereby enabling real-time communication. It’s because of this special feature that Webhooks are sometimes referred to as “Reverse APIs”. In simple terms, a Webhook is an HTTP POST request which is triggered as a result of a certain event in the system.

In this multi-part series, we will start off by explaining what Webhooks are, how they work and finally end it with a practical real world use case. The table of contents is listed below. You can jump to the relevant section by clicking on the corresponding link,

1. Webhook Operational Stages
   1. Stage 1 – Subscription
   2. Stage 2 – Event Trigger
   3. Stage 3 – HTTP POST Request
   4. Stage 4 – Processing the Payload
2. An Example
3. Webhooks vs Traditional APIs
4. Hypothetical Scenario
5. Sample Zoom Webhook Response

Webhook Operational Stages

The implementation of a Webhook typically involves following stages

Stage 1 – Subscription

• An application subscribes to an event on another system
• The subscribing application provides a URL where it wants to receive notifications from the destination system.

Stage 2 – Event Trigger

• When a specific event occurs on the system, it triggers the Webhook

Stage 3 – HTTP POST Request

• The system sends an HTTP POST request to the URL specified by the subscribing application
• This request contains relevant data about the event in the payload.

Stage 4 – Processing the Payload

• The subscribing application processes the payload and takes appropriate actions on it.

An Example

Let’s say we have a proprietary application that’s hosted on the cloud or we are using any public SaaS solution like Zoom. Our objective is that we want our application to be notified every time a certain specific event occurs on our Zoom instance. For example, when a certain Zoom meeting is being recorded, we want our application to get notified when the recording is done & available for download. This is a good real world example which can help us keep track of how many meetings have been recorded and downloaded for reporting purposes.

• As shown in the above diagram, our application first has to subscribe to a specific event on the opposite system which is Zoom in this example. This is a one time activity. As a part of this “Subscription” request, our application has to have a URL on which it is supposed to receive the Webhook response from Zoom.

• If the subscription process is successful, then every time that event to which we have subscribed occurs, the system will send its notification to the URL that we provided in the previous step via HTTP POST method. For our example, this would mean that Zoom will send an HTTP POST message with an appropriate payload. It is then up to the local application to decide how to process that incoming payload.

Webhooks vs Traditional APIs

The “Webhook Event Trigger” step we discussed above will continue to execute as long as the subscription is active. The application doesn’t have to keep subscribing to the destination system every time it wants to get notified. This is where the concept of “Webhooks” differs from the traditional API based request-response mechanism. In the traditional API based system, the source system has to actively poll the destination to retrieve information. In other words, it follows the “Pull” process where the source is pulling information from the destination. In the “Webhooks” based system, it’s quite the opposite. The destination system is usually the one taking the lead in pushing information to the source without the source having to request it repeatedly. That’s why Webhooks fall under the “Push” umbrella.

As is clear from the above diagram, the source application sends a typical CRUD REST request and the destination system sends a corresponding response in either JSON or XML. This exchange of messages will have to happen every time the source application needs information from the destination system. This sort of arrangement is not conducive to scenarios that demand constant sharing of real time information.

Hypothetical Scenario

Imagine a scenario where you have built an application to receive notifications every time a router’s CPU goes above 90%. With the API based system, that application would have to constantly keep sending GET request to the router’s REST API (if available) to obtain its CPU usage. If we wanted to capture CPU usage every second then that would mean sending 3600 GET requests every hour. This not only is totally unsustainable but also requires taking into account other design factors like API rate limiting and causing additional CPU spikes because the router has to process these incoming barrage of GET requests. In a nutshell, this is a really bad scenario.

The advantages of Webhooks start becoming more & more apparent when we start veering towards situations where frequent real time exchange of information is paramount. With Webhooks, our application has to subscribe to the CPU event on the router (if such an option is available) just once and the rest of the heavy lifting of informing the application if CPU goes above 90% will be handled by the router itself.

One important point to keep in mind is that since the destination system which is triggering the Webhook has to submit a POST request, it is imperative that it has reachability to the subscribing application’s URL over the internet. If we go back to the Zoom example we discussed earlier, then Zoom should be able to reach that URL over the internet.

Sample Zoom Webhook Response

The following is a sample response from Zoom that is sent when “Recording Complete” Webhook event is triggered. This is what the subscribing application will receive from Zoom and it is then up to the application to decide what to do with this data.

{
  "event": "recording.completed",
  "event_ts": 1626230691572,
  "payload": {
    "account_id": "AAAAAABBBB",
    "object": {
      "id": 1234567890,
      "uuid": "4444AAAiAAAAAiAiAiiAii==",
      "host_id": "x1yCzABCDEfg23HiJKl4mN",
      "account_id": "x1yCzABCDEfg23HiJKl4mN",
      "topic": "My Personal Recording",
      "type": 4,
      "start_time": "2021-07-13T21:44:51Z",
      "password": "132456",
      "timezone": "America/Los_Angeles",
      "host_email": "jchill@example.com",
      "duration": 60,
      "share_url": "https://example.com",
      "total_size": 3328371,
      "recording_count": 2,
      "on_prem": false,
      "recording_play_passcode": "yNYIS408EJygs7rE5vVsJwXIz4-VW7MH",
      "recording_files": [
        {
          "id": "ed6c2f27-2ae7-42f4-b3d0-835b493e4fa8",
          "meeting_id": "098765ABCD",
          "recording_start": "2021-03-23T22:14:57Z",
          "recording_end": "2021-03-23T23:15:41Z",
          "recording_type": "audio_only",
          "file_type": "M4A",
          "file_size": 246560,
          "file_extension": "M4A",
          "play_url": "https://example.com/recording/play/Qg75t7xZBtEbAkjdlgbfdngBBBB",
          "download_url": "https://example.com/recording/download/Qg75t7xZBtEbAkjdlgbfdngBBBB",
          "status": "completed"
        }
      ],
      "participant_audio_files": [
        {
          "id": "ed6c2f27-2ae7-42f4-b3d0-835b493e4fa8",
          "recording_start": "2021-03-23T22:14:57Z",
          "recording_end": "2021-03-23T23:15:41Z",
          "file_type": "M4A",
          "file_name": "MyRecording",
          "file_size": 246560,
          "file_extension": "MP4",
          "play_url": "https://example.com/recording/play/Qg75t7xZBtEbAkjdlgbfdngAAAA",
          "download_url": "https://example.com/recording/download/Qg75t7xZBtEbAkjdlgbfdngAAAA",
          "status": "completed"
        }
      ]
    }
  },
  "download_token": "abJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJodHRwczovL2V2ZW50Lnpvb20udXMiLCJhY2NvdW50SWQiOiJNdDZzdjR1MFRBeVBrd2dzTDJseGlBIiwiYXVkIjoiaHR0cHM6Ly9vYXV0aC56b29tLnVzIiwibWlkIjoieFp3SEc0c3BRU2VuekdZWG16dnpiUT09IiwiZXhwIjoxNjI2MTM5NTA3LCJ1c2VySWQiOiJEWUhyZHBqclMzdWFPZjdkUGtrZzh3In0.a6KetiC6BlkDhf1dP4KBGUE1bb2brMeraoD45yhFx0eSSSTFdkHQnsKmlJQ-hdo9Zy-4vQw3rOxlyoHv583JyZ"
}

---

This was part 1 of this multi-part series. I hope you found this post helpful to understand the great importance that technologies like Webhooks holds in modern applications. In the upcoming posts, we will go over some practical use cases & take a deep dive into how Webhooks can be utilized in modern Operations environment.

Please feel free to drop your feedback/suggestions, if any. Until then, Happy Learnings!!

Let’s connect on LinkedIn