Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Crafting a Great Webhooks Experience

John Sheehan
November 20, 2015

Crafting a Great Webhooks Experience

Presented at API Strategy and Practice 2015 #apistrat

John Sheehan

November 20, 2015
Tweet

More Decks by John Sheehan

Other Decks in Technology

Transcript

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

    View full-size slide

  2. "user defined
    callbacks made
    with HTTP POST"

    View full-size slide

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

    View full-size slide

  4. HTTP Push
    Notifications

    View full-size slide

  5. A Reverse API

    View full-size slide

  6. 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 full-size slide

  7. 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 full-size slide

  8. 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 full-size slide

  9. Implementing
    Webhooks

    View full-size slide

  10. 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 full-size slide

  11. Problem #1:
    Error Handling

    View full-size slide

  12. > POST /callback
    < 400 Bad Request

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  15. Error Handling
    Suggestions

    View full-size slide

  16. 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 full-size slide

  17. 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 full-size slide

  18. 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 full-size slide

  19. Problem #2:
    Flooding

    View full-size slide

  20. Active
    Queues


    View full-size slide

  21. Problem #3:
    Security

    View full-size slide

  22. > POST http://localhost:3000

    View full-size slide

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

    View full-size slide

  24. DoS Attack Vector

    View full-size slide

  25. Proving the Source

    View full-size slide

  26. Validation
    Techniques

    View full-size slide

  27. Request
    Signing

    View full-size slide

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

    View full-size slide

  29. Security
    Suggestions

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  33. Developer
    Experience

    View full-size slide

  34. Payload Design

    View full-size slide

  35. Mirror API
    Resources

    View full-size slide

  36. Complete
    Documentation!

    View full-size slide

  37. Accept Multiple
    Callback URLs

    View full-size slide

  38. Debugger &
    Logs

    View full-size slide

  39. Manual
    Retries

    View full-size slide

  40. Generate
    Test Callbacks

    View full-size slide

  41. Tunneling
    Recommended: ngrok.com

    View full-size slide

  42. Thank you!
    Questions?
    [email protected]
    Try Runscope free:
    runscope.com

    View full-size slide