Post on 21-Feb-2017
Giuliano Iacobelli, Stamplayg@stamplay.com
Webhooks do’s and dont’s: what we learned integrating +100 APIs
g@stamplay.com
Lego for APIsStamplay is a low-code platform that provides a visual interface to drag&drop
connectors and creates integration workflows between services
g@stamplay.com
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.
g@stamplay.com
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
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
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
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
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
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.
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
g@stamplay.com
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
g@stamplay.com
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
g@stamplay.com
Renewing subscriptions Avoid sending webhooks to endpoints that are no longer active
by implementing a subscription renewal logic
g@stamplay.com
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
g@stamplay.com
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
g@stamplay.com
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
g@stamplay.com
Webhooks debugging Receives HTTP requests and captures the data for later inspection
g@stamplay.com
Webhooks toolkit: Ngrok Secure introspectable tunnels to localhost
g@stamplay.com
Questions? g@stamplay.com
Try Stamplay: stamplay.com
Thank you!