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"
}