When you need to design a webhook infrastructure yourself, there are some considerations you need to make.  This blog post discusses the most important ones.

Event Names

Make sure you have consistent, clear and descriptive event names.  This helps in adoption of your webhooks and it makes a more professional impression. Event names can be CRUD-based.  In case you want to leverage webhooks to perform data synchronisation, such a crud-based approach is more than enough.  Some examples:

• User.Created
• Device.Updated
• Employee.Deleted
• Order.Updated

You can also make the event names more declarative.  This result in more fine-grained events, which allows to subscribe to very specific lifecycle events of certain entity types. Some examples:

• User.AddressChanged
• Device.Disconnected
• Employee.Retired
• Order.Shipped

Event Data

Make sure you have consistent, clear and descriptive event content.  This helps in adoption of your webhooks and it makes a more professional impression.  Each event should contain an event name, a unique event Id and a timestamp.  Optionally, you can give consumers control on the content-type (JSON / XML).

In many cases, all entity data is included in the event.  This improves the user experience and makes the solution less chatty, because the event consumer has all data it needs.  Potentially, this approach could result in large event payloads.

Another common approach, is to have only the entity Id included in the event.  This requires the event consumer to make an additional call to your API infrastructure, in order to get the details of the entity.  This adds an extra security layer to your solution, because additional authentication is required to retrieve the entity details from the API.  The event payloads are smaller, but the solution is a little bit chattier, due to the extra roundtrip.

Registration

The registration process should be simple, user-friendly and well-documented, just like any API.  This ensures fast adoption.  Provide ways to subscribe with multiple URL’s, on different event types.  It’s also important to offer several security options: add custom HTTP header, a custom key or a shared secret.  Give your consumer the option to choose the desired content-type.

The registration of a webhook can be done through a UI, which makes it easy to get started quickly.  This is the most convenient option during development phase.  Registration through an API, on the other hand, is more desired for production-ready solutions.  Ideally both UI and API options are available.

Un-registration

Webhook consumers don’t want to subscribe forever, they need a way to opt-out.  This can be both UI or API based.

In most cases, this registration is explicit. You are subscribed to specific events, until you explicitly unregister yourself.  Some webhook systems add a certain expiration to the webhook subscriptions.  There should be the option to override the default expiration settings.

Conclusion

A thorough analysis is required, when you want to provide webhooks to your API consumers.  My preferred approach is:

• Use declarative event names
• Only include the entity Id in the event data
• Foresee registration via an API, including the option to provide a shared secret.
• Foresee explicit un-registration via an API

Hope this one was helpful.
Toon