Crafting a Great Webhooks Experience

Presented at API Strategy and Practice 2015 #apistrat

Transcript

1. Crafting a Great Webhooks Experience John Sheehan CEO, @Runscope
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.
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
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