Why and when to use Webhooks

I will let you look up the wikipedia definition and dive right into my own explanation. Webhook is primarily a web mechanism of one way notification, that your software produces and a third party software consumes. By allowing webhooks in your software, you are giving your customers a way of extending our core product by integrating custom processes into your product that react in real time.

The key here is "real time". Instead of writing data at the end of a process into database and some custom batch process picking it up as part of a nightly routine, you can send the data at the end of the process for each instance.

How do Webhooks work?

At its most elementary form webhook is a http post request to a pre-configured location sent at a specific point in the core product process. When you reach some point in your business logic that warrants a notification, you check if there is a webhook configured that is waiting for the notification and if there is one you send the pertinent data to the configured URL as HTTP post request. Two requirements of webhook are:

1. Your software provides a way to configure a URL that is listening for notification.
2. It sends the configured URL the pertinent data about some point of business logic that is reached in a predetermined format.

Lets say you develop enterprise software with supports various business processes. Your customers will want to integrate custom processes that are specific to them that need to be triggered at various points of the business process. For example a customer might want an automatic email generated whenever an invoice is past due. This is generic enough to be part of your core product but if they want to completely customize the email that you possibly cannot support from within your software. So one way to handle to this scenario is to post a notification with invoice data to the webhook URL and let them create a custom process to generate the email with their custom modifications.

When do Webhooks make sense?

1. To extend your core product by letting others build custom processes that react to your core business logic in real time.
2. If you build enterprise software you would constantly have enhancements requests for implementing custom implementations for some big customer to link a process in your software to another process in a different enterprise software. Webhooks could let you off the hook in many of these instances.
3. To supplement standard functionality for unexpected scenarios. A tech savvy customer can use the webhook enabled logging mechanism from your software and create a twitter feed out of it.
4. When you have asynchronous architecture to improve user experience. For example payment solutions like Paypaluse webhooks to send feedback on if the user's payment is successful or not. The time to process the payment sometimes may take more time than you are willing to let your customer wait so you complete the process for the user without waiting for the payment confirmation and send them an email confirmation at a later point of time.

Things to consider

1. Carefully consider the data you share via the webhook. In most cases a lot of data required by your core product is not required by custom process.
2. Webhooks can be unreliable in cases where the post requests are lost in traffic due the nature of internet itself. So cannot be used for business critical operations without a proper fallback mechanism.
3. URL parameters is not the only way to send data to a webhook. You can use other parts of the HTTP request such as data and headers.
4. Secure the communication channel with webhook. Require that the webhook URL uses https.
5. Let the 3rd party configure a private key along with the webhook URL to make sure that they know that they are receiving communication from your software.
6. There will be multiple points in your business logic where you would want to send off notifications, so there should be a good interface for your customers to configure the webhook data.
   
   Good example of an interface to let customers add a webhook from moltin.com. Here Motlin is letting you configure webhooks to listen to when a CRUD operation occurs within their process.
   
   
   

If you are interested to know more about how the term webhook came to be, check the video on webhooks.org.