How to Structure Webhooks

When planning your webhook events, the most important thing to consider is the request body and headers; that is, how you want to represent each event. Webhooks are hard to change once people begin using them, so spend some time thinking about this.

The format/content-type should match your API, if you have one—the most common is JSON. The data objects in your webhooks should also match your API; for instance, if you send a webhook when a user is created, include the same object that is returned when requesting that user from your API.

Example

Here are three different webhook events:

// X-MyApp-Event: user.created
{
  "id": 1,
  "name": "Matz"
}
// X-MyApp-Event: comment.created
{
  "id": 123,
  "user": {
    "id": 1,
    "name": "Matz"
  },
  "body": "I love webhooks!"
}
// X-MyApp-Event: comment.updated
{
  "id": 123,
  "user": {
    "id": 1,
    "name": "Matz"
  },
  "body": "Webhooks are so cool."
}

Note that all three events include the "X-MyApp-Event" header; this allows the endpoint to respond differently to different events:

case webhook.headers["X-MyApp-Event"]
when "comment.created"
  # Store reference to comment
  store_comment(webhook.body)
when "comment.updated"
  # Update reference to comment
  update_comment(webhook.body)
else
  # Skip other events (not handled yet)
end

Also note that the user object is included in each event. If you were to request that user from the API, you'd get back the following response:

// GET /api/v1/users/1
{
  "id": 1,
  "name": "Matz"
}
How to Version Webhooks »
© 2020-2021 Honeybadger Industries, LLC