The difference in one table
An API call is a question you ask when you want an answer now: send this, fetch that. A webhook is a standing instruction: when this happens, tell me at this URL. The API puts you in control of timing; the webhook puts the event in control.
Polling an API for changes is the tell you needed a webhook: asking "anything new?" every minute is expensive on both sides and still up to a minute late. The push arrives once, when it happened.
The split shapes how I design ours. The raw API is more transactional: one request, one effect, an answer now. Credentials follow the same line. API keys should just be for REST, with webhooks trusted by signature instead of by key.
API shape matters as much as API existence. George, our CEO, logged the receipt on our own template API: changing logo_width across 12 templates took him 24 round-trips, 12 reads and 12 writes carrying the full sections array each time, where a JSON-Patch endpoint or a brand-level default would collapse it to one. When the question is repetitive, the answer belongs in the contract.
In email, you need both
Email makes the split concrete. The API sends the message: POST, message ID back, done. The webhook reports its life afterwards: delivered, opened, clicked, bounced, complained, each POSTed to your endpoint as it happens. Under the hood each maps to a canonical name, opened to email:open, clicked to email:click, bounced to email:bounced, delivered to email:delivered, complained to email:complained, so a handler keys on one vocabulary. Feedback arrives classified, hard and soft bounces with subtypes and complaint feedback types, and every event carries a deduplication key so a replayed POST cannot double-count.
Build with only the API and you're blind after the send. Build with only webhooks and you can't send. The two are one loop: act through the API, react through the webhook, and let your agent close the loop, a bounce fires, the contact gets suppressed, and you read about it afterwards.
A real trace of that loop from our own ops: a send reports six failures, and every one reads contact email is suppressed from earlier bounce suppressions. That's the system working: yesterday's webhook events protecting today's API calls, with nobody watching a dashboard in between. The counters behind that loop hold one invariant: provider open webhooks are mirrored into email:open_total, so the number stays true whichever writer records it. And the loop runs in your direction too: POST /v1/my/events accepts arbitrary event names with a custom data payload and fires flow triggers, so your own product events can start flows exactly the way email events do.
George, our CEO, tracks where the traffic actually goes: 94% of our usage is now via API, not UI. That number is why the contract gets guarded like one. After a weekend breaking change got past us, we stood up an 80/20 API canary so a future contract break surfaces in CI or within about 24 hours, not through customer complaints. The same conservatism applies where we are the consumer: product fixes, like one to Stripe checkout return URLs, are scoped so they never change Stripe webhook semantics, subscription creation, pricing, or payment state transitions.
The unglamorous failure modes sit at the edges. Nick, on our team, caught app/uninstalled and the order and customer webhooks not being registered at runtime under a legacy install flow: no auto-deactivate on uninstall and no real-time sync until the flow was fixed. Chong, on our team, traced a failed verification to nothing more than a leading www on the domain, and webhook improvements keep landing from there. Slack webhook verification and delivery even ships as a product feature. The pattern generalises: the webhook you did not register, verify, or version is the one that costs you.
Agents bend the pull-push split in an interesting way. An agent is transient: it runs, acts, and exits, so it usually can't host the public HTTPS endpoint a webhook wants to POST to. Agents poll. The first fully productized MCP client on our platform checks campaign state every fifteen minutes, and across all our agent traffic, 43 percent of tool calls are telemetry queries: agents asking what happened, then deciding what to do next. Push for servers, pull for agents, the same events underneath both.
Full parameters and responses live in the REST API docs and the API reference.
Go deeper
The mechanics: webhooks explained. Before production: test your webhook and secure it. Whichever you choose, the receipts feed the same things: bounce rate and the reliability of transactional email.