What is a Webhook and how do you create it?

Photo by Federico Beccari on Unsplash

What is a Webhook

According to RedHat, A webhook is an HTTP-based callback function that allows lightweight, event-driven communication between 2 application programming interfaces (APIs). Webhooks are used by a wide variety of web apps to receive small amounts of data from other apps, but webhooks can also be used to trigger automation workflows in GitOps environments.

In simple terms, if your app is using any SaaS application, then you need to submit an API to them and whenever they receive any new changes for your data in their platform, they will trigger that API to notify your system about the change

webhook in simple terms

Webhook Architecture

Webhook generally works with architecture where there are many relationships between consumer and provider. E.g. A web application can integrate a payment provider. Whenever a change occurs in the provider data store, it will notify the consumer on an API that is already being registered with the provider via the consumer. Also to handle events from such providers, generally, providers create a package or library to handle their own events or functions in more easier way. One of the popular examples of such a consumer and provider relationship is the stripe webhook.

Use incoming webhooks to get real-time updates

How does stripe work?

First, when creating an App with Stripe, a consumer has to pass certain information into their system which includes a POST API request that will be triggered whenever a certain event occurs, we can create one or more webhooks for different events. Similarly, stripe has a list of packages that a developer can use in their application which will help to perform actions on Stripe servers like creating charges, transactions, etc.

Set up your development environment

How to create Webhook?

Enough theory let's move to actual implementation and create such an environment where we can see how webhook works. Before moving to actual code, I am assuming you are familiar with what a REST API, JSON, and How to create your server in your preferred language. For this article, I am using NodeJS and Express but that will be irrelevant since our goal is to learn webhooks and not a programming language.

Create consumer and provider server

For this demo, Let’s create 2 servers. Consumer and Provider, creating a separate folder for them would be better and I am using boilerplate code to start a server.

Boilerplate for an express app running on port 8080

Now, we have 2 servers running for both provider and consumer, we can add some sample routes into them for an entity, let's name it customer since each SaaS has a customer entity generally we will follow the same pattern.

Routes sample for consumer and similarly for provider

Now, we have the server up and running for both consumer and provider with some sample routes, we can move to actual implementation and add raw functionalities to our app

Creating Event in Provider

The provider is also a web application and it also has lots of functions for its own client rather than putting SaaS clients first, generally, the volume of requests can be many based on the number of clients you have. So we do not want to block our main thread with all these requests and we will follow the event-driven pattern and create a separate event to trigger our webhook. Let's create a file event.js that will have our async event.

boilerplate for our webhook event

To test this we can update one of the routes to call following the webhook

routes.get('/', (req, res) => {
    runWebhook('test')
    res.json('provider work!')
})

// output
I hear a webhook! test

Now, let's attach a sample datastore, considering each URL will come from a database.

webhook complete on event

Explanation and Usage

Now, our webhook is ready. Here we created a mock database that will contain a list of all consumer and their webhook URL. Whenever we receive a request for webhook, we will get data and then whatever URL we have, we will make a POST request to that URL with the data that is updated and the potential event.

You may add more conditions and functions into event handler, also you can add more event handlers based on number of events your provider applications has and how each event works and of course create a documentation related to each event and how a consumer can integrate it and expected payload

Integrating webhook into provider and passing required data for consumer

After running this, your consumer will receive a request on their registered URL. In this example, I’ve given an idea on an external route but the event trigger point can be anything and is not limited to API only, the event can be triggered on database hooks, load, API, or any async calls

Now, on the consumer end, we need to create a route named /webhook that will be listening to our changes and events.

creating consumer webhooks and handling event

This is all. That’s how webhook works and how you can integrate it. But it is not limited to adding routes and calling only. You also need to add security to your webhook and let only those requests that are required

Security Practices

To protect your webhook and its data, one should follow a couple of practices but not limited to

• Use whitelisting webhook only — before sending data to webhook, see if the user has explicitly given permission to use that webhook URL, and have 2 2-step verification
• Encrypt your data before sending and let the user create a decrypt key — Ask the user to submit a secure key and use that key to encrypt data before sending, since the consumer has given us a key then they can use that to decrypt
• Signature verification — Add a mechanism to signature verification
• Backup flow and API Key — Add a way for users to generate an API key and use it if they want to fetch certain entities or resources so that for any downtime, their application will not get hampered.

Conclusion

To conclude, webhooks are very important aspect of SaaS development, and if you are planning to create a SaaS application then you should get familiar with it as well.

You can find source code for this article in Github repository. On the last note, when creating a SaaS application and specifically webhook application. Try to find the relevant application that your app resembles and see what process they are following and stick to that. Keep adding more security layer to your SaaS platform and see how can you prevent any loop wholes. Remember its not your application data at risk but also the client who is working with your and security of there data as well

With this note, I hope you learn something new today and Happy Coding!