Design Considerations for Webhooks

Event Names

Make sure you have consistent, clear and descriptive event names.  This helps for the adoption of your webhooks and it makes a more professional impression. Event names can be CRUD-based.  If you want to leverage webhooks to perform data synchronization, 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 results 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 the 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 round-trip.

Registration

To ensure fast adoption, the registration process should be simple, user-friendly and well-documented, just like any API.  It’s also wise to provide ways to subscribe with multiple URL’s, on different event types.  It’s 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, this 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 desirable for production-ready solutions.  Ideally both UI and API options are available.

Deregistration

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 deregister 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