Crafting a Great Webhooks Experience

54b75f6fbf4434162bfcda6b0cb9b86b?s=47 John Sheehan
November 20, 2015

Crafting a Great Webhooks Experience

Presented at API Strategy and Practice 2015 #apistrat

54b75f6fbf4434162bfcda6b0cb9b86b?s=128

John Sheehan

November 20, 2015
Tweet

Transcript

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

  2. None
  3. None
  4. None
  5. None
  6. None
  7. "user defined callbacks made with HTTP POST"

  8. "Webhooks are the easiest way to remotely execute code." --

    Jeff Lindsay once when we were talking
  9. HTTP Push Notifications

  10. A Reverse API

  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.
  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.
  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.
  14. None
  15. Implementing Webhooks

  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)
  17. Problem #1: Error Handling

  18. > POST /callback < 400 Bad Request

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

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

    <Response></Response>
  21. Error Handling Suggestions

  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.
  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.
  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.
  25. Problem #2: Flooding

  26. None
  27. Active Queues ↪ ↪

  28. Problem #3: Security

  29. > POST http://localhost:3000

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

  31. DoS Attack Vector

  32. Proving the Source

  33. Validation Techniques

  34. Key Sharing

  35. Request Signing

  36. Re-fetch > POST /callback > { id: 123 } >

    GET /users/123 < { id: 123 } Webhook Callback App Code
  37. Security Suggestions

  38. Validate your requests. Document it well! Resolve IPs before making

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

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

    request. Consider proxying. Consider subscription validation for high-volume cases.
  41. Developer Experience

  42. Payload Design

  43. Fat vs.Thin

  44. Mirror API Resources

  45. Complete Documentation!

  46. Tooling

  47. Accept Multiple Callback URLs

  48. Hooks API

  49. Debugger & Logs

  50. Manual Retries

  51. Generate Test Callbacks

  52. Tunneling Recommended: ngrok.com

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