Imagine this: your organization has a television at the office that lists articles that your team has published using your content management system (CMS).
Included on the screen are headlines, times of publish, authors, and a number of other data points.
In this situation, there are presumably two systems:
- The CMS used to create and publish the articles and their data
- The app on the television that displays that article data
But how are the two systems able to communicate with one another to achieve the above?
One popular way is webhooks.
What are webhooks?
A term coined and promoted in 2007 by a developer named Jeff Lindsay, a webhook allows different apps to send user-defined callbacks to one another via HTTP POST requests. In plainer English, webhooks allow notifications to be sent from one app to another app when a certain event occurs. The user gets to determine which event triggers the notification, and all notifications are sent in real time.
The fact that these notifications are sent in real time is important.
Using the television/CMS example above, let's say that I'm an editor-in-chief of a publication at a news organization. It's on my shoulders to enable my team members to complete their work. As part of this effort, I need to respond to conversations they have within our CMS as quickly as possible, and that means I need to know when comments are made, even if I'm not in the CMS myself.
Without webhooks, I could have the CMS send me data about comments every thirty minutes, every three hours, etc. (a process called polling)—but if a time-sensitive comment is made in the CMS, and I don't know about it right away (and therefore don't respond to it right away), then I'm not doing my job as well as I need to be.
How do webhooks work?
Webhooks are handy when you don't have direct access to the system or app from which you are trying to receive data, just like the app running on the television didn't have access to the article metadata in the CMS.
Webhooks are typically set up by REST APIs, and both the CMS and the app in the example above have one. The app's REST API does two things:
- It calls the CMS's REST API and tells it to send metadata over when X event occurs (let's say when an article is published)
- It provides an endpoint (a URL) to which that metadata should be sent when X event occurs
Once this webhook is established, the app sits tight. All sorts of things go on in the CMS, and eventually, an article gets published. The CMS checks its webhooks when this happens, sees that the app has made one, and then pushes the metadata (the headline, author, time of publish, etc.) over to the URL that the app provided.
Let's walk this into a real-life example:
My young child is in daycare. It's important for me to know when she goes down for a nap so that I can adjust the time she goes to bed. I call the daycare and request that they call me at the number I provide when my daughter starts napping. This action of me calling the daycare and asking that they send me a notification when a specific event happens—that's me calling the daycare's REST API, generating the webhook, and providing the endpoint at which the daycare can return the information I requested (my phone number).
Next, I go about my workday. At 12:03 p.m., I get a call from the daycare telling me that my daughter has gone down for a nap. I now have the information I needed, I can act on it however I need to, and therefore, I enjoy the value of the webhook I established with the daycare.
It's important to note that webhook concept creator Jeff Lindsay also evangelized two other use cases for webhooks beyond the notifications discussed above:
- Integration of different web apps (using webhooks to take data from one app, reformat it, and pass along to another app)
- Modification of web apps (using webhooks to allow plugins or other modifications to an app depending on what that app permits)
Brightspot and webhooks
Using Brightspot, you can create webhooks in two ways. The first way is the standard way you create a webhook—through configuring APIs; however, Brightspot also allows webhooks to be easily created via its editorial UI.
In the image above, the user is able to simply navigate to a section within Brightspot CMS, select REST Management API from a dropdown list, and then see an interface with all necessary elements laid cleanly out for them.
After entering a name for the API and defining the API's URL (not the same as the webhook's URL—a conversation for another day), the user can click "Add Webhook," which pops open a content edit form where they can define the URL to which metadata is sent as well as what event triggers the webhook.
Topics are the events discussed above. Many of these come out-of-the-box with Brightspot: Publish, Conversation, Translation, Workflow—and quite a few more than those. Depending on which topic the user chooses to "listen" to, the UI morphs to add deeper configuration functionality.
From those examples alone, outside apps can receive notifications when something is published, when a comment is made in the conversation widget, when a translation has transitioned to any number of states, or when an asset progresses through a workflow.
All of this is highly actionable information for an editor.
Content filters allow me to dig down with even greater granularity as to which specific event triggers a notification. Maybe the user only wants the webhook for a particular site in their multisite environment, or maybe only for the notification to trigger the first time a specific event occurs.
As software-as-a-service platforms continue to enjoy widespread popularity across the internet, webhooks remain a valuable way to get these platforms to communicate, and more importantly, ensure the users of these platforms are well aware of relevant changes the moment they are made. And with Brightspot, you get the tools to make webhooks however you prefer to do so.
What is a webhook?
How does a webhook work?
What's the difference between a webhook and an API?
A webhook is an API pattern; therefore, it becomes difficult to compare and contrast the two in a traditional way. For practical purposes, consider a webhook as a simple API that pushes data from one system to another without serving any other function.
What are webhooks used for?
What are some examples of a webhook?
- A digital publisher needs to be notified the moment an article is ready to be approved for publication on the website thought the company's CMS. A webhook will send an SMS alert to her phone to let her know the article is ready for final approval.
- An eCommerce business needs to know when a new order has been received and to alert the necessary team members that this item is ready for fulfillment. A webhook can trigger an email notification to all the necessary team members as well as update the relevant workflows in the system.
- A restaurant owner wants to know whenever a new customer review is received that is lower than two stars. A webhook can alert the owner via text that the negative review has been received and he can respond accordingly.
- An accounts-receivable team wants to know when a vendor has submitted a new invoice through the company's shared invoicing email address. A webhook can update the appropriate accounts database with the vendor's invoicing details to ensure speedy processing of the invoice as well as consistent financial documentation.