Webhooks do's and dont's: what we learned after integrating +100 APIs - Giuliano Iacobelli - Codemotion Rome 2017
1 like500 views
The document discusses best practices for integrating webhooks as part of API design, emphasizing the importance of a robust setup that includes essential components like explicit event types, payloads, and security measures. It highlights the need for APIs to provide detailed information, manage subscription renewals, and ensure security in webhook communications. Additionally, the document touches on debugging and toolkits for effectively working with webhooks.
Webhooks do's and dont's: what we learned after integrating +100 APIs - Giuliano Iacobelli - Codemotion Rome 2017
- 1. Giuliano Iacobelli, Stamplay [email protected] Webhooks do’s and dont’s: what we learned integrating +100 APIs
- 3. [email protected] Lego for APIs Stamplay is a low-code platform that provides a visual interface to drag&drop connectors and creates integration workflows between services
- 4. [email protected] Token based Auth (e.g OAuth2) Machine readable docs (Swagger, RAML, IO docs) Webhooks HATEOAS Key requirements for APIs in the automation era Simple, consistent, flexible, friendly, explorable via URL and use web standards where they make sense.
- 5. [email protected] Key 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 (Swagger, RAML, IO docs) Webhooks HATEOAS
- 12. [email protected] 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. [email protected] 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. [email protected] 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. [email protected] 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. [email protected] 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. [email protected] Batch vs Single Services providing high frequency / volume of data might opt to make less calls and batch data into an array
- 18. [email protected] Subscribing to events using multiple URLs 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 CRUD API • a payload URL: the server endpoint that will receive the webhook payload • events list: which events would you like to subscribe to • (optional) the content type
- 19. [email protected] Subscribing to multiple events to single URL 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
- 20. [email protected] Fine grained control on events you want to listen on 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
- 21. [email protected] Renewing subscriptions Avoid sending webhooks to endpoints that are no longer active by implementing a subscription renewal logic
- 22. [email protected] API for Webhooks aka REST Hooks 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
- 23. [email protected] Securing Webhooks 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
- 24. [email protected] Webhooks debugging Receives HTTP requests and captures the data for later inspection
- 25. [email protected] Webhooks toolkit: Ngrok Secure introspectable tunnels to localhost