Webhooks do's and dont's

As modern applications are becoming more and more a composite of APIs and the serverless architectures are getting more attention, API providers can’t afford any longer to expose only traditional REST endpoints.

When it comes to designing webhooks there is nothing really close to a standard in the HTTP API literacy. Every service implements webhook differently leading to many different flavors of webhooks implementations out there.

After integrating APIs from more than 100 different services I can tell that the way a service exposes webhooks can be a deal breaker. So here are the things that make us happy when we need to integrate with a service exposing webhooks.

Transcript

1. Giuliano Iacobelli, Stamplay g@stamplay.com Webhooks do’s and dont’s: what we learned integrating +100 APIs
2. g@stamplay.com Lego for APIs Stamplay is a low-code platform that provides a visual interface to drag&drop connectors and creates integration workflows between services
3. g@stamplay.com
4. g@stamplay.com
5. g@stamplay.com Token based Auth
 (e.g OAuth2) Machine readable docs (OpenAPI, RAML, IO docs) Webhooks HATEOAS Requirements for APIs in the automation era Simple, consistent, flexible, friendly, explorable via URL 
 and use web standards where they make sense.
6. g@stamplay.com Requirements for APIs in the automation era Simple, consistent, flexible, friendly, explorable via URL 
 and use web standards where they make sense. Token based Auth
 (e.g OAuth2) Machine readable docs (OpenAPI, RAML, IO docs) Webhooks HATEOAS
7. g@stamplay.com WEBHOOKS = HTTP PUSH NOTIFICATIONS
8. g@stamplay.com
9. g@stamplay.com
10. g@stamplay.com
11. g@stamplay.com
12. g@stamplay.com Consumer sets up a server to listen for webhooks
 Consumer registers webhook URL with provider
 Provider starts making request to webhook URL when event happens Webhook Setup
13. g@stamplay.com Consumer sets up a server to listen for webhooks
 Consumer registers webhook URL with provider
 Provider starts making request to webhook URL when event happens Webhook Setup
14. g@stamplay.com Consumer sets up a server to listen for webhooks
 Consumer registers webhook URL with provider
 Provider starts making request to webhook URL when event happens Webhook Setup
15. g@stamplay.com Webhook anatomy Webhooks are fundamental pieces of an API today and a simple notification is no longer enough, as an API provider you need to do the heavy lifting for your users • a verb: POST • an explicit event type: which could be subscribed by any user (for Github: pull_request, fork, commit, issues, etc.. ) • a payload: containing the relevant data for the related event 
 • including: the resource itself, the sender (user who triggered the webhook) 
 • constant data structure • a security hash: to ensure webhook was delivered by the rightful authority 
 • for Github: sharing a common secret used to generate a hash from the payload • an ID
16. g@stamplay.com Fat payload vs Thin payload Provide as much information as possible about the event that is being notified, as well as additional information for the client to act upon that event.
17. g@stamplay.com Batch vs single Services providing high frequency / volume of data might opt to make less calls and batch data into an array
18. g@stamplay.com Subscribing to events using multiple URLs Some services route the same type of notification (topic) to more than one URL
19. g@stamplay.com Subscribing to multiple events to single URL Other services let you bind to an URL multiple topics
20. g@stamplay.com API for Webhooks aka REST Hooks Webhooks shuold be able to be configure programmatically, and guess what? You can build an API for that.
21. g@stamplay.com Topics / Event types Mailchimp’s webhooks are strongly tied to lists so they have 
 implicit notion of the resource they are tied to
22. g@stamplay.com Topics / Event types Cisco Spark threat webhooks as a standalone resource, with it’s own set of CRUD methods. Subscription to topic must include resource and event type.
23. g@stamplay.com Topics / Event types Most common implementation is to structure a hierarchy of topics by resources
24. g@stamplay.com Fine-grained topics vs Fine-grained resource watch Decide whether you want to have customer subscribe for events on each single specific resource or to subscribe by type of resource.
25. g@stamplay.com Renewing subscriptions Avoid sending webhooks to endpoints that are no longer active by implementing a subscription renewal logic
26. g@stamplay.com Renewing subscriptions Avoid sending webhooks to endpoints that are no longer active by implementing a subscription renewal logic
27. g@stamplay.com Renewing subscriptions Avoid sending webhooks to endpoints that are no longer active by implementing a subscription renewal logic Three days..
28. g@stamplay.com Renewing subscriptions Avoid sending webhooks to endpoints that are no longer active by implementing a subscription renewal logic
29. g@stamplay.com Securing Webhooks The service shall provide a way to validate that they were not sent by an untrusted third- party. At least a lightweight static shared secret is a good start.
30. g@stamplay.com Securing Webhooks More secure strategies include hash signature of the JSON notification. The digest is then sent using a dedicated header and can be verified by the receiving webhook. Client Server Create subscription + secret Notification + Additional header with hash signature of the JSON notification
31. g@stamplay.com Receives HTTP requests and captures the data for later inspection Secure introspectable tunnels to localhost Webhooks toolkit Some must-have tools when working with webhooks
32. g@stamplay.com Giuliano Iacobelli g@stamplay.com stamplay.com APIDays Coupon (6 months 50% off) APIADDICT Thank you!