Recently, I wound up in a discussion with a coworker about webhooks. (Specifically, my hope that Okta offers them. I’ve spent several hours reading this documentation and I still can’t tell.) She wasn’t familiar with them, and neither was the customer who we were looping in as part of the larger discussion. So, I wound up explaining webhooks as follows:
Think of our two services as two people: you, in the back of the office, and your coworker George who sits near the kitchen and can see the microwave. You want to know if the popcorn you just put in the microwave is done, but can’t wait around in the kitchen. (Your office is very strict about loitering.)
If you just have two APIs with no webhooks, it’s the same as you having to message your coworker on Slack every few minutes in order to ask if the popcorn is done. It works (and you’ll get the info you need), but it’s annoying—especially if your coworker responds with a bunch of info you don’t care about. (No one is that interested in CrossFit/Paleo/vegan protein options/LuLaRoe, George.)
Webhooks are the equivalent of a loud microwave ding. You hang out in your part of the office, and the microwave proactively shouts at you when the popcorn is done—at which point you can go get your afternoon snack, without having to pretend to care about George’s CrossFit/Paleo/vegan protein options/LuLaRoe.
This is an a incredibly surface-level explanation, and doesn’t get at all the benefits of webhooks (particularly if you’re operating in an environment where real-time response is of particular interest). But, I do think it’s a fun and useful exercise to try to break down somewhat technical concepts into non-technical analogies—if for no other reason than it is helpful in a sales context when trying to explain your value to a non-technical customer.