Event-Driven APIs with Webhooks

Arrr! The concept of a Webhook is simple. Webhooks are a way to receive valuable information when it happens, rather than continually polling for that data and receiving nothing valuable most of the time. In this talk, discover the wonderful world of webhooks, real-life applications, and best practices.

https://goo.gl/YmlmU6

Transcript

1. The Wonderful World of Webhooks &
   Event-Driven APIs
   Yos Riady
   yos.io
   goo.gl/YmlmU6
   

   View Slide

2. View Slide

3. View Slide

4. The Perils of Polling
   The Why and What of
   Webhooks
   Background Webhooks Examples
   Best
   Practices
   Conclusion
   The How and some
   real-life applications
   Summary and further
   learning
   How to do
   webhooks well
   

   View Slide

5. The Perils of Polling
   

   View Slide

6. View Slide

7. book pls
   How APIs work
   GET /books/1
   

   View Slide

8. here you go!
   How APIs work
   

   View Slide

9. View Slide

10. 1.5%
    The percentage of polling requests that are actionable :(
    

    View Slide

11. Polling is a hack.
    and you should be sad :(
    

    View Slide

12. The Perils of Polling
    The Why and What of
    Webhooks
    Background Webhooks Examples
    Best
    Practices
    Conclusion
    The How and some
    real-life applications
    Summary and further
    learning
    How to do
    webhooks well
    

    View Slide

13. View Slide

14. What is a webhook?
    

    View Slide

15. View Slide

16. check this out
    How Webhooks work
    

    View Slide

17. {
    "id": "evt_19lV34GiPuIq2Ki5UbuHx0fz",
    "created": 1486697174,
    "data": {
    “title”: “Webhook Design 101”
    “author”: {}
    },
    "type": "book.published"
    }
    

    View Slide

18. thanks!
    How Webhooks work
    200 OK
    

    View Slide

19. View Slide

20. Don’t call me. I’ll call you.
    

    View Slide

21. View Slide

22. Webhooks in the wild
    

    View Slide

23. View Slide

24. View Slide

25. Reasons to use Webhooks
    

    View Slide

26. Why use Webhooks #1: Performance
    Webhooks are 66 times more efficient than traditional polling. Only 1.5% of polls
    were actionable. With webhooks, the value is expected to be near 100%.
    ● Reduce server load
    ○ Decreases the number of servers you need
    ○ Increases the number of clients you can support
    ○ Save on server costs
    ● Drop bandwidth usage by orders of magnitude
    

    View Slide

27. Why use Webhooks #2: User Experience
    ● A smarter, more idiomatic solution to real-time
    ○ As opposed to polling every n-minute intervals
    ○ Industry best practice
    ● Improved developer experience
    ○ Over 80% of developers prefer webhooks compared to polling
    ○ Spend less time on the quirks of polling
    

    View Slide

28. The Perils of Polling
    The Why and What of
    Webhooks
    Background Webhooks Examples
    Best
    Practices
    Conclusion
    The How and some
    real-life applications
    Summary and further
    learning
    How to do
    webhooks well
    

    View Slide

29. Webhook Design 101
    Provider makes an HTTP POST
    request when an event
    happens
    Notifications
    Consumer registers a webhook
    URL with the provider
    Subscriptions
    Consumer sets up a server to
    listen / consume webhook
    events
    Setup
    

    View Slide

30. What’s in an event?
    ● Event name
    ○ follows a noun.verb convention
    ● Event payload
    ○ Should match your API resource
    ● ID
    {
    "id": "evt_19lV",
    "created": 1486697174,
    "data": {
    “title”: “Webhook Design 101”
    “author”: {}
    },
    "type": "book.published"
    }
    

    View Slide

31. Webhook Event Naming Convention
    namespace.noun.verb
    ● account.updated
    ● charge.succeeded
    ● billing.subscription.cancelled
    ● ping
    

    View Slide

32. Subscriptions API
    

    View Slide

33. View Slide

34. Event Dispatch & Delivery
    In your Application code
    1. An event is triggered somewhere in your system
    2. Insert a task to deliver hooks for the event and user (async)
    3. Continues execution as per normal
    Event Delivery Task
    A. Look up any existing subscriptions for the particular event and user
    B. Loop over existing subscriptions and POST the payload
    C. Perform any cleanup, failure, or retry logic
    

    View Slide

35. For scalability, use a proper queue
    

    View Slide

36. The Perils of Polling
    The Why and What of
    Webhooks
    Background Webhooks Examples
    Best
    Practices
    Conclusion
    The How and some
    real-life applications
    Summary and further
    learning
    How to do
    webhooks well
    

    View Slide

37. Best Practice #1: Event Types
    

    View Slide

38. Best Practice #2: Multiple Webhook URLs
    

    View Slide

39. Best Practice #3: Security
    ● Use HTTPS
    ○ prevents man-in-the-middle snooping
    ● IP whitelisting
    ○ for consumers to verify the event source
    ● Send a shared secret with the outgoing payload
    ○ Basic Auth
    ○ for consumers to verify the authenticity of the event source
    ○ X-Mandrill-Signature
    ● Verify an Event using its ID
    ○ for consumers can verify an event with the provider
    ○ Providers expose an Events API
    

    View Slide

40. Best Practice #4: HTTP Responses and Retries
    ● Event handlers should be idempotent
    ○ Delivery is guaranteed ‘at least once’
    ● Return 2xx To acknowledge receipt of a
    webhook event
    ○ All other status codes will indicate that the event was not
    received
    ● Non-received events should be resent
    ○ Stripe will resend events every hour for 3 days until it’s
    received
    ○ Exponential backoff
    ○ Support manual triggers
    

    View Slide

41. Best Practice #5: Documentation
    Webhook subscription and the each event type should be well-documented.
    

    View Slide

42. Best Practice #6: Performance
    

    View Slide

43. The Perils of Polling
    The Why and What of
    Webhooks
    Background Webhooks Examples
    Best
    Practices
    Conclusion
    The How and some
    real-life applications
    Summary and further
    learning
    How to do
    webhooks well
    

    View Slide

44. Summary
    ● Software is becoming increasingly interconnected
    ● The problems with traditional polling
    ● What webhooks are and why we use them
    ● How to do webhooks well
    

    View Slide

45. Thanks
    Yos Riady
    yos.io
    

    View Slide

46. Questions?
    Yos Riady
    yos.io
    

    View Slide