The mechanism, end to end
Three parts. You register an endpoint URL with the platform. When an event fires, the platform sends an HTTP POST to that URL with a JSON payload describing what happened. Your endpoint returns 200 to acknowledge.
{
"event": "opened",
"message_id": "msg_9f2c",
"recipient": "[email protected]",
"occurred_at": "2026-07-17T02:14:09Z"
}
Miss the 200 and the platform retries with exponential backoff, which is why your handler must be idempotent: the same event can arrive twice, and processing it twice should change nothing.
The details that separate toys from production
Acknowledge fast, work later: return 200 immediately and queue the processing, because a slow handler looks like a failed delivery and triggers retries. Verify the signature before trusting a byte, every Nitrosend event is signed with HMAC-SHA256. And treat event order as advisory: networks reorder, so key your logic on the event timestamp, not arrival time.
Do those three and webhooks become what they should be: your system's reflexes. An agent watching the stream suppresses a bounced address before the next campaign ever queues.
And audit the pipeline itself, because event streams fail silently. We lived this one: our provider reported 10,706 bounces in 48 hours while our internal activity table logged 69. A handler missed one lookup path and silently dropped 99 percent of bounce events, no log, no metric, no retry. Count both ends of your pipe. The gap is where reputations die.
The fix is worth copying. Unmatched bounce and complaint events now persist to a dedicated forensic table with the full raw payload, instead of vanishing, while high-volume opens and clicks stay log-only so the table stays lean. And the sending side mirrors it: the API accepts an idempotency key per message, so your own retries can't double-send. Reliability is symmetrical. Dedupe what comes in, dedupe what goes out.
Full parameters and responses live in the REST API docs and the API reference.
Go deeper
Deciding between pull and push: webhook vs API. Wiring one up: test a webhook before it meets production traffic.