Webhooks: From Zero to Hero
You’re in a restaurant waiting for your takeaway meal, and the meal order meal screen is damaged. You get asked to take a seat. While doing so, you start a Facetime conversation with a friend.
The simplest and smartest thing you can do is wait until your name is called, and in the meantime, keep up with the conversation. However, imagine a second use case, where you’re an impatient person and every five minutes, you ask if it’s ready.
In the end, we all know that the second approach makes less sense, as asking for more updates will not make the process faster. And will most likely, make you lose track of the conversation.
The same problem happens in many business applications when you don’t know when the answer will arrive. To solve that, such applications keep asking, even though it won’t make a difference most of the time.
Webhooks solutions come to solve problems like these. Such architecture decisions may have a significant optimization impact on your project.
Index:
- What’s a webhook?
- How do webhooks interactions get orchestrated?
- Let’s create a practical example!
- Let’s prove it works!
- Conclusion;
# What’s a webhook?
Let’s start by analyzing what Wikipedia has to say about that:
A webhook in web development is a method of augmenting or altering the behavior of a web page or web application with custom callbacks. These callbacks may be maintained, modified, and managed by third-party users and developers who may not necessarily be affiliated with the originating website or application.
A bit too abstract? Let’s make it concrete.
A webhook is a mechanism where we use an HTTP POST operation to notify a specific client. The client will get specified by defining which HTTP endpoint should get called whenever a specified event occurs.
You may wonder, why POST? The answer is that such a method will allow the server to send any data within the body request (JSON/XML).
By event, we can look into some use cases such as:
- Receiving a message from a chat (e.g Telegram);
- Liked photo (e.g Instagram)
- Financial stock prices (e.g any broker)
- Getting an email every time a pull request gets created (e.g GitHub)
We’re talking about an efficient way of asking the server if any changes as occurred.
The chat room seems like a great example. Without thinking about webhooks, which interval should we use to check for new messages? 20 seconds? 5 minutes? 1 hour?
It depends. Some folks may take 10 hours to answer a simple message like me, or they could also take only 10 seconds. Let’s suppose we check for new messages on a 10-minute average. Overall, we would do over 144 requests in a day, about 4320 a month. And don’t forget, different people have different answer timings.
A webhook implementation would reduce those 4320 requests to a value around zero. The server would be the one notifying you.
# How do webhooks interactions get orchestrated?
Usually, you have a significant amount of events. Those events will trigger the notification process between application X and yours.
We can take the GitHub use case example. GitHub allows you to define webhooks without much work.
Such webhooks as:
- Branch or tag deletion;
- Code scanning alerts;
- Commit comments;
- Project created, updated, or deleted;
- Visibility changes;
- And so many others;
In the end, we only need to create a webhook on the server, specify which endpoint should get reached and which event you want to trigger such a mechanism.
# Let’s create a practical example!
To exemplify the concepts explained above, we’ll use the GitHub webhooks.
To avoid much work in setting up an application environment, let’s use a serverless solution, the Azure Functions.
If it’s your first time hearing such technology, I firstly suggest having a look at the following article:
Note: You can easily use the Azure free tier in case you don’t have a subscription.
2. On the Azure portal, click on ‘+ Create a Resource’ and then ‘Function App’. You should be able to see the following page:
3. On the ‘runtime stack’, select ‘Node’. You’re free to fill the remaining fields as you wish according to your location and subscription. After filling in everything, click on the create button.
4. Click on ‘Go to resource’. On the left side menu bar, click on ‘Functions’ > ‘+ add’. You should be able to see something like:
5. Select ‘HTTP Trigger’ and give a name to your function. You can leave the ‘Authorization level’ field as ‘Function’. Click on the ‘Add’ button.
6. On the ‘Code + Test’, insert the following code:
7. Click on ‘Get Function URL’ and copy the URL for future reference.
After these steps, our function is created and ready to be used. Save the inserted code, and let’s pass it to the GitHub tasks.
8. After creating a GitHub account, create a simple repository like the following one.
9. Click on the ‘Settings’ tab, and then on ‘Webhooks’.
10. Click on ‘Add Webhook’. A similar form page should appear.
11. Fill the form with the following data:
- Payload URL: Define the POST client endpoint mentioned in the earlier sections.
- Content-Type: Select the ‘application/json’ option.
- Secret: This is one way to avoid unwanted communications to your client. By defining a secret, the same on the client and the server side, only both will understand each other. Leave the field blank for the sake of simplicity.
- Events: Select ‘Let me select individual events’ and let’s choose the ‘Watches’. Such an event will trigger the webhook whenever your repository gets a star.
Click on ‘Add Webhook’.
# Let’s prove it works!
The remaining task is to check whether our webhook is working as expected.
- Click on the Edit button from the created webhook.
2. At the end of the page, on ‘Recent Deliveries’ select the most recent one and check the response.
Hurray! We got our webhook working!
# Conclusion
Hopefully, I could help you to understand a bit more about webhooks and how important they are.
Feel free to share your experience with such architecture with the community through the comments.
Let me know what you think in the comments.
