Crafting a Great Webhooks Experience

Presented at API Strategy and Practice 2015 #apistrat

Transcript

1. Crafting a Great
   Webhooks Experience
   John Sheehan
   CEO, @Runscope
   

   View Slide

2. View Slide

3. View Slide

4. View Slide

5. View Slide

6. View Slide

7. "user defined
   callbacks made
   with HTTP POST"
   

   View Slide

8. "Webhooks are the
   easiest way to remotely
   execute code."
   -- Jeff Lindsay once
   when we were talking
   

   View Slide

9. HTTP Push
   Notifications
   

   View Slide

10. A Reverse API
    

    View Slide

11. Provider makes request to
    URL when an event happens.
    Consumer sets up a server to
    listen for callbacks.
    Consumer registers callback
    URL with provider.
    

    View Slide

12. Provider makes request to
    URL when an event happens.
    Consumer sets up a server to
    listen for callbacks.
    Consumer registers callback
    URL with provider.
    

    View Slide

13. Provider makes request to
    URL when an event happens.
    Consumer sets up a server to
    listen for callbacks.
    Consumer registers callback
    URL with provider.
    

    View Slide

14. View Slide

15. Implementing
    Webhooks
    

    View Slide

16. url = get_callback_url()
    data = get_webhook_payload_json()
    try:
    resp = requests.post(url, data=data)
    if not resp.ok:
    _logger.error(resp.content)
    except Exception as e:
    _logger.error(e)
    

    View Slide

17. Problem #1:
    Error Handling
    

    View Slide

18. > POST /callback
    < 400 Bad Request
    

    View Slide

19. > POST /callback
    < 302 Found
    < Location: http://
    

    View Slide

20. > POST /callback
    < 200 OK
    < Content-Type: text/plain
    <
    

    View Slide

21. Error Handling
    Suggestions
    

    View Slide

22. Be lenient in what you accept
    back if you can reasonably guess.
    Retry failed callbacks with
    exponential back off.
    Decide if redirects are to be
    followed or not.
    

    View Slide

23. Be lenient in what you accept
    back if you can reasonably guess.
    Retry failed callbacks with
    exponential back off.
    Decide if redirects are to be
    followed or not.
    

    View Slide

24. Be lenient in what you accept back
    if you can reasonably guess.
    Retry failed callbacks with
    exponential back off.
    Decide if redirects are to be
    followed or not.
    

    View Slide

25. Problem #2:
    Flooding
    

    View Slide

26. View Slide

27. Active
    Queues
    ↪
    ↪
    

    View Slide

28. Problem #3:
    Security
    

    View Slide

29. > POST http://localhost:3000
    

    View Slide

30. > POST http://foo.lvh.me
    

    View Slide

31. DoS Attack Vector
    

    View Slide

32. Proving the Source
    

    View Slide

33. Validation
    Techniques
    

    View Slide

34. Key Sharing
    

    View Slide

35. Request
    Signing
    

    View Slide

36. Re-fetch
    > POST /callback
    > { id: 123 }
    > GET /users/123
    < { id: 123 }
    Webhook Callback
    App Code
    

    View Slide

37. Security
    Suggestions
    

    View Slide

38. Validate your requests.
    Document it well!
    Resolve IPs before making
    request. Consider proxying.
    Consider subscription validation
    for high-volume cases.
    

    View Slide

39. Validate your requests.
    Document it well!
    Resolve IPs before making
    request. Consider proxying.
    Consider subscription validation
    for high-volume cases.
    

    View Slide

40. Validate your requests.
    Document it well!
    Resolve IPs before making
    request. Consider proxying.
    Consider subscription validation
    for high-volume cases.
    

    View Slide

41. Developer
    Experience
    

    View Slide

42. Payload Design
    

    View Slide

43. Fat vs.Thin
    

    View Slide

44. Mirror API
    Resources
    

    View Slide

45. Complete
    Documentation!
    

    View Slide

46. Tooling
    

    View Slide

47. Accept Multiple
    Callback URLs
    

    View Slide

48. Hooks API
    

    View Slide

49. Debugger &
    Logs
    

    View Slide

50. Manual
    Retries
    

    View Slide

51. Generate
    Test Callbacks
    

    View Slide

52. Tunneling
    Recommended: ngrok.com
    

    View Slide

53. Thank you!
    Questions?
    john@runscope.com
    Try Runscope free:
    runscope.com
    

    View Slide