An agent needs to know when new mail arrives in its inbox, and DimeBox supports two fundamentally different ways to find out: ask repeatedly (polling) or get told automatically (webhooks). Neither is strictly better — they trade latency, complexity, and resource use against each other differently.
Polling means calling GET /api/inboxes/{slug}/messages on some schedule and checking whether anything new has shown up since the last check. It's the simpler of the two to implement — no public endpoint to expose, no signature verification, just a scheduled HTTP call an agent already knows how to make. The tradeoff is inherent: poll too infrequently, and there's real latency between a message arriving and the agent noticing. Poll too frequently, and most of those calls return nothing new, wasted effort for both the caller and the API (though reads are free on DimeBox, so the cost here is latency and complexity, not money).
A webhook means registering a webhook_url at inbox creation and getting a signed POST pushed to it the moment the message.received event fires — see Webhook Notifications for Agent Inboxes: A Practical Guide for the full setup, including signature verification. This removes the latency-versus-waste tradeoff entirely: the agent finds out essentially as soon as a message lands, without guessing at a polling interval. The cost is infrastructure — the agent (or whatever's acting on its behalf) needs a publicly reachable endpoint to receive the webhook, and has to verify its signature correctly before trusting it.
Only one event currently triggers a webhook: message.received, covering both receive channels. Outbound status changes — a send moving from queued to sent or failed — aren't pushed; tracking those still requires polling the messages endpoint and checking status. See Queued Delivery: Why Your Agent Shouldn't Wait on SMTP for why sends are asynchronous in the first place.
For anything time-sensitive — an agent that needs to react to a reply quickly, or a multi-agent workflow where one agent is waiting on another's message — a webhook is almost always the better fit, since the latency cost of polling compounds across every exchange in a workflow. For a background process that checks in occasionally and isn't blocked on a fast reaction (a daily digest, a low-urgency support queue), polling on a modest interval is simpler to run and perfectly adequate.
Nothing prevents running a webhook as the primary notification path while still polling on a longer interval as a fallback — useful if an agent's webhook endpoint could plausibly be down or unreachable at the moment a message arrives, and a missed push shouldn't mean a missed message forever. For the full mechanics of reading what's accumulated either way, see Reading a Mailbox's History: Pagination and Message IDs Explained.