Webhooks are growing in popularity and they’re a great way for SaaS providers like Salesforce, Slack, Stripe, Trello, Marketo, Twilio, HubSpot (and many, many others) to efficiently publish changes for clients to ingest in real-time. In this post, I’ll go through the What, Why, and When for using webhooks.
What are Webhooks?
A webhook is an HTTP callback from an API that describes meaningful changes in data from that application. There are two types of webhooks: Incoming and Outgoing webhooks which are for pushing data in and getting data out of an API, respectively. These webhooks can be asynchronous or synchronous. If it’s an asynchronous webhook, the API only needs a response that the message was delivered (usually just an HTTP status code), but if it’s synchronous, the API needs to wait for a message back (e.g. request-reply/response).
For application integrations, it’s most common to use asynchronous outgoing webhooks, which publish events by the use of an HTTP POST, in an XML or JSON HTTP payload, to a destination URL. These types of webhooks are typically triggered from a web form submission, a predefined workflow in a SaaS app, or maybe some scheduled custom code.
Why use Webhooks?
Webhooks serve a variety of purposes. The key benefit is that regardless of the state of your API, the backend database you use, or the complexities of your application, webhooks provide clients the value of complex data queries in an out-of-the-box, near real-time, and easy-to-ingest XML or JSON format.
If you’re developing a webhook for your application, the overhead is fairly painless because you can control the code and [backend] query-execution, and you don’t necessarily need to manage the webhook’s destination infrastructure and processing.
If you’re using webhooks from an aforementioned SaaS app, you’ll be able to subscribe to or create workflow rules that determine when webhooks fire with the changed data.
Here’s a look at the simple setup of a Marketo webhook rule (where “Tokens” are the fields from the Marketo data):
Here’s HubSpot’s Webhook API’s payloads (super-easy JSON!):
When to Use Webhooks?
System Administrators can often configure (usually in a point-and-click manner) a webhook to occur on predefined events, such as:
- A Lead is converted to an Opportunity (alert the marketing system)
- An Opportunity is set to Closed Won (alert the finance system)
- An Order is confirmed (alert the eCommerce system)
- A webinar has completed (alert the CRM system)
- A Contact registers for a session (alert the event management system)
- A record is deleted from the system (alert the integration system)
That Admin also sets up any Endpoint URLs where the payloads will be POSTed to, and integrations will know what to do with it.
Other times, workflow rules are customized to a specific customer need and then reference a webhook:
- Each time a lead score surpasses 200
- Each time a user creates a Post in the Community with the Status “High Importance”
- Each time a customer invoice record with status of “unpaid” goes over 90 days
Each of these uses of webhook offers a time-efficient and low-cost/maintenance way to deliver specific data.
As an integration developer, I love working with outgoing webhooks. There’s no need to worry about populating URL/URI parameters; filtering for net-changes; tracking deleted records, pagination, unstructured data; etc. Developing for outgoing webhooks allow me to focus on the payload – typically sent as URL Encoded form data, or raw text – and then send it to my target destination. No fuss.
In a future post, I’ll talk about the infrastructure needed to capture async/sync outgoing webhooks, and the common data formats I’ve encountered.
First Published February 19, 2018
About the Author
Nate Keefe is a Product Manager at TIBCO Software.