Building Webhooks: Webhook Payload Breakdown August 2022 · ian

Intro

Whether you are building your own webhooks solution or using a webhook service like HostedHooks, implementing webhooks come with a bunch of design decisions that need to be taken into account. With the goal of educating and helping others designing webhooks we are going to go through our thinking for each of these design choices. In his post we will discuss the JSON payload that gets sent to the webhook subscribers. We’ll go through the structure of the payload and all of the key value pairs.

The key to the HostedHooks payload design was to create a payload that would be standard enough to make integrations easy and consistent, but also customizable enough for the webhook sender to be able to dynamically update. See below for how we hoped to achieve that.

HostedHooks Webhook Payload

This is an example of the JSON payload structure that we use at HostedHooks. We will run through this as a point of reference.

{
  "data": {
    "foo": "bar"
  }, 
  "version" : "1.0",
  "event_type": "user.created",
  "created" : "2022-06-01T17:48:14.981-04:00"
}

Let’s break it down.

Data object

The first key is a data object which points to the custom data payload that the webhook subscribers will receive. This object contains key, value pairs of data specific to each user and what they want to send to their users. The user is able to put whatever data they want in this payload. This is the only non custom data input in the HostedHooks payload.

{
  "data": { "foo":"bar" },
  ...
}

Version Data

Next up is the version key. This was designed so the webhook subscriber could determine which version of the payload they are receiving. Webhook senders will inevitably need to update their payloads with new or changed data, when doing so they will they bump the version and this lets the webhook subscriber only receive the updated payload when they explicitly request it

{
  "version" : "1.0",
  ...
}

Event Type

Next up is the event_type key. This value is the specific event that has been triggered This is necessary so the webhook subscriber can determine which event they are receiving.

Some webhooks are designed with event type in the header, which is something we considered. After some thought we felt that it didn’t make sense separating that data outside of the context of the rest of the payload. I can see the benefit of knowing the event type before accessing the payload but in our opinion the benefit is negligible.

{
  "event_type": "user.created",
  ...
}

Created Timestamp

Lastly is the created key. This is the a timestamp of when the webhook message was sent.

{
  "created" : "2022-06-01T17:48:14.981-04:00",
  ...
}

Conclusion

As you can see we tried to focus on making the payload as simple as possible, while still including all of the necessary data. The goal here was to do our best to make the webhook subscriber/consumer side of integration as easy as possible. I hope this was helpful. Let us know if you have any questions.