What's in a webhook request?

David Multer — Fri, 29 Mar 2019 00:53:10 +0000

Webhooks are a simple, yet powerful approach for delivering event notifications to your application. In this article, I will focus on the aspect of webhooks that is most meaningful to you as an application developer, the payload. The payload contains data fields that convey the meaning of an event. These fields are typically sent in the body of a webhook HTTP request.

The exact format of this payload is entirely up to the source that sends you the webhook request. The most important data field describes the type of event that occurred. A service that handles mailing lists might include event types like subscribed, unsubscribed, and sent email. Each of these events would then include additional fields to identify a subscriber, delivery details, and so on. The type of event can be indicated in many ways, but is most clearly described when it follows a noun.verb format.

Here's an example from the Stripe API documentation. Note the type field with a value of invoice.created. The event name follows the noun.verb format, making the intent of the event crystal clear.

{
  "id": "evt_1CiPtv2eZvKYlo2CcUZsDcO6",
  "created": 1530291411,
  "type": "invoice.created",
}

Events often include fields that are shared across multiple event types. The event type I just described is one example of a common field. Another common field you often find is used to represent the date and time that the event was generated. This timestamp can be represented in a variety of formats, timezones, and different levels of precision. The timestamp can be used to help identify duplicate events and ensure the correct ordering of events. Some events also include an identifier (ID) field to uniquely identify every event. This can be used as a more precise way to eliminate duplicate events.

Looking again at the Stripe example, you'll find the id and created fields provide both ID and timestamp values. The timestamp is in UNIX Epoch time seconds format. Often you'll find the time specified as a string in ISO-8601 format as well.

{
  "id": "evt_1CiPtv2eZvKYlo2CcUZsDcO6",
  "created": 1530291411,
  "type": "invoice.created",
}

In a few cases, you can control the fields that are sent in the payload. Datadog allows full configuration of custom payloads with whatever fields and values you like. Zendesk and Leanplum have standard event types that also let you configure additional custom fields.

The content type used in the HTTP request will affect the structure of the payload. The most common format you'll find is JSON, which is very simple to process in a variety of application programming languages. A less common format is HTML form URL encoded data. You'll need to decode key/value pairs for each type of event in this case. You might find the content encoded using XML in rare cases. You'll need to use XML parsing libraries specific to your application programming language for these payloads.

Most payloads will be relatively small and convey the critical information you need to process a specific event. Other webhook sources expect you to make additional API requests to their service to collect more details related to the event. In a few rare cases, you'll want to take special care when the payload size becomes very large. A few of these webhook sources can include file attachments directly in the payload that can be many megabytes in size.

The payload for most webhook requests contains a single event. A few webhook sources will batch these events into a single webhook payload. Batched events can help save you from a flood of HTTP requests when many events are sent at a time, but it then becomes your responsibility to handle processing for all events. Acknowledging a batched request lets the webhook source know that you have taken on this responsibility. Typically the payload will have a list of events in the webhook payload.

Here's an example of batched events from Mailjet. The event field is used to identify the event type, the time field is in UNIX Epoch time format, and the MessageID field is unique for every event.

[
  {
    "event": "open",
    "time": 1552244670,
    "MessageID": 456,
  },
  {
    "event": "open",
    "time": 1552244731,
    "MessageID": 457,
  },
]

You should find detailed developer documentation on the webhook source website explaining exactly how they handle all the payload topics I've covered in this article. Be aware that it can be challenging to track down and understand all these details for each webhook source and the events they support.

Hookalu is here to help you tackle webhook complexity so you can focus on delivering business value to your customers.

Originally published at hookalu.com.

What are webhooks?

David Multer — Sun, 17 Mar 2019 23:35:08 +0000

Ever since Jack Lindsay originally coined the term webhook in 2007, people have been writing articles trying to answer the question What is a webhook? It may seem a complex question to answer, but understanding webhooks is actually much easier to grasp than you might think. Most great ideas in software come from simple and flexible ideas in real life. The same holds true for webhooks. So let me start with something we all can relate to.

Everyone loves to eat out at a restaurant at least once in while. Restaurants provide a service where customers can enjoy a (hopefully) great meal. Every restaurant offers their own unique combination of food, setting, atmosphere, and service hoping to gain you as a customer. The great restaurants work hard to make the experience so good, you can't wait to come again.

One experience that is common to nearly every restaurant is how you are seated at a table. You walk in the door and expect to leave your information including your name, number of people in your party, and maybe a phone number. In return, you immediately hear when your table is ready. Whether you are notified by simply hearing your name called out, a buzz from a paging coaster, or a text message on your phone, you expect fast notification regarding the status of your request for a table.

Let's look at the steps that are essential to a great experience in such an exchange.

First you need to register your intent to receive a notification from the restaurant when your table is ready. This registration must include some minimum information that lets the restaurant host know how to contact you.
Second you must receive the promised notification message from the restaurant that your table is ready.
Finally the restaurant expects you to return to the host and let them know you received the notification and are ready to eat!

This is basically all you need to know to understand webhooks. A web application or service is the same as the restaurant. Each one is trying to win you as a customer. Many of these web services offer methods for customers to register for event notifications that provide even more possibilities than letting you know your table is ready.

You must first register a public URL endpoint with the service to receive notifications. This is how the service knows how to contact you.
The service will send an HTTP request to your URL endpoint with a specific message containing details of the event. The specific details of the event are often referred to as the payload. You must provide the business logic (code) that understands how to handle the event.
You acknowledge successful receipt of the event in your response to the HTTP event request. This is typically communicated via a status code in your response.

When we talk about webhooks, we are talking about the two parties (service and customer) along with the steps in this exchange. Webhooks are a simple and flexible idea built on the powerful foundation of the Web.

Originally published at hookalu.com.

DEV Community: David Multer

What's in a webhook request?

What are webhooks?