Webhooks do's and dont's: what we learned after integrating +100 APIs
25
Giuliano Iacobelli, Stamplay [email protected] Webhooks do’s and dont’s: what we learned integrating +100 APIs
-
Upload
giuliano-iacobelli -
Category
Technology
-
view
62 -
download
0
Transcript of Webhooks do's and dont's: what we learned after integrating +100 APIs
Giuliano Iacobelli, [email protected]
Webhooks do’s and dont’s: what we learned integrating +100 APIs
Lego for APIsStamplay is a low-code platform that provides a visual interface to drag&drop
connectors and creates integration workflows between services
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.
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
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
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
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
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
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.
Batch vs Single Services providing high frequency / volume of data might opt to make less calls
and batch data into an array
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
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
Renewing subscriptions Avoid sending webhooks to endpoints that are no longer active
by implementing a subscription renewal logic
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
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
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
Webhooks debugging Receives HTTP requests and captures the data for later inspection
Webhooks toolkit: Ngrok Secure introspectable tunnels to localhost
