Events and webhooks
Replies, bounces, LinkedIn messages and dropped sessions as signed webhooks, or as one stream on GET /v1/events.
A reply lands, an email bounces, someone answers on LinkedIn, a connected account drops its session: each of these is an event on your workspace. You can receive them two ways, from the same stream:
- Webhooks: register a URL and every event is POSTed to it, signed, within seconds.
GET /v1/events: read the stream with a cursor. One call covers every inbox and connected account, in place of oneemail.messagesorlinkedin.messagesrun each. This is the route for an agent, which has no server to receive a webhook; the MCP tool isevents.
Both are free. Events are kept 30 days.
Event types
| Type | When | Data |
|---|---|---|
email. |
an email landed in one of your inboxes | inbox, inbox_, message_, thread_, from, to, cc, subject, preview, text, text_, links, labels, received_ |
email. |
the recipient's mail server accepted an email you sent | inbox, inbox_, message_, thread_, recipients, at |
email. |
an email you sent bounced | the same, plus type (Permanent or Transient) and sub_ |
email. |
a recipient marked your email as spam | the same, plus type and sub_ |
email. |
an email was refused before it left | the same as email., plus reason |
gmail. |
an email landed in a connected Gmail account | account, account_, message_, provider_, thread_, from, to, cc, subject, text, sent_, has_ |
linkedin. |
someone messaged a connected LinkedIn account | account, account_, chat_, message_, text, sender_, sender_, sender_, sent_ |
linkedin. |
a connected LinkedIn account has a new connection, usually an accepted invitation | account, account_, name, provider_, public_, profile_ |
instagram., whatsapp. |
someone messaged a connected Instagram or WhatsApp account | same fields as the LinkedIn message |
account. |
a connected LinkedIn, Instagram, WhatsApp or Gmail account lost its session and cannot send or read until it signs in again | network, account, account_, status (CREDENTIALS, ERROR or STOPPED), next_ (the . call that returns a reconnect link) |
account. |
the account is back | network, account, account_, status (RECONNECTED) |
Field names match the capability that reads the same thing: an email.received event carries what a single email.messages read carries (the full text, or the HTML body read as text when the email has no text part, and the links of the HTML body), and a gmail.received event what a row of gmail.messages carries. To answer a reply, pass data.message_id as in_reply_to on email.send or gmail.send, or data.chat_id on linkedin.message, instagram.message or whatsapp.message.
Messages your own account sends do not produce message_received events. linkedin.new_connection can arrive up to 8 hours late: LinkedIn has no live signal for it, so the relation list is checked at random intervals. An invitation sent with a note also shows up sooner as a linkedin.message_received when the person answers.
The envelope
{
"id": "evt_5b1c...",
"type": "email.received",
"created_at": "2026-10-03T10:00:02Z",
"data": {
"inbox": "hello@acme.dev", "inbox_id": "hello@acme.dev",
"message_id": "<abc123@mail.acme.dev>", "thread_id": "thd_789",
"from": "Jane Doe <jane@example.com>", "to": ["hello@acme.dev"], "cc": [],
"subject": "Re: quick question", "preview": "Sure, Tuesday works",
"text": "Sure, Tuesday works for me.", "text_from_html": false, "links": [],
"labels": ["received"],
"received_at": "2026-10-03T10:00:00Z"
}
}
Read the stream
GET /v1/events?after=evt_...&types=email.received,linkedin.message_received&limit=50
Oldest first. The answer carries items (each an envelope as above), count, has_more and next_after: store next_after and pass it as after on the next call to get only what is new; when nothing is new, next_after is the cursor you sent. With no cursor yet, since takes an ISO 8601 timestamp to start from; with neither, the stream starts at the oldest event still kept, and so does a cursor older than 30 days. types takes a comma-separated list (an unknown type answers 400 invalid_request); limit is 50 by default and 200 at most.
curl "https://api.routergrowth.com/v1/events?after=$LAST_EVENT_ID" \
-H "Authorization: Bearer $ROUTERGROWTH_API_KEY"
Register a webhook
POST /v1/webhooks
curl -X POST https://api.routergrowth.com/v1/webhooks \
-H "Authorization: Bearer $ROUTERGROWTH_API_KEY" -H "Content-Type: application/json" \
-d '{"url": "https://hooks.acme.dev/routergrowth", "events": ["email.received", "email.bounced", "linkedin.message_received"]}'
events is the list of types to receive; leave it empty for all of them, including types added later. description is an optional label. The URL must be https, without credentials in it, and resolve to a public address; it is checked again before every delivery. The answer (201) carries the endpoint and its secret, shown this once: store it.
{"webhook": {"webhook_id": "whk_...", "url": "https://hooks.acme.dev/routergrowth", "description": "",
"events": ["email.bounced", "email.received", "linkedin.message_received"], "enabled": true,
"disabled_reason": "", "failing_since": null, "last_delivery_at": null, "last_status_code": null,
"created_at": "2026-10-03T09:58:00Z", "secret": "whsec_..."},
"note": "Store the secret now: it signs every delivery and is not shown again."}
A URL that fails those checks, or an unknown event type, answers 400 invalid_request. A workspace has up to 5 endpoints; a sixth answers 409 conflict.
GET /v1/webhooks your endpoints, and every event type with its description
GET /v1/webhooks/{webhook_id} one endpoint and its last 20 deliveries
PATCH /v1/webhooks/{webhook_id} change url, events, description or enabled
DELETE /v1/webhooks/{webhook_id}
POST /v1/webhooks/{webhook_id}/test send one signed webhook.test event now and see how your server answered
Each delivery shows its status (pending, sending, delivered or failed), attempts, the last status_code and error, and next_attempt_at. The test sends a webhook.test envelope once, outside the stream and without retries, even to an endpoint that is switched off, and answers delivered, status_code, error and the event it sent.
Webhooks are managed with an API key or from the dashboard. A connected app (claude.ai, ChatGPT) can read events but cannot register an endpoint.
Verify a delivery
Every delivery is a POST with the envelope as its JSON body and these headers:
Content-Type: application/json
User-Agent: RouterGrowth-Webhooks/1
RouterGrowth-Signature: t=1791021602,v1=5f2b...
RouterGrowth-Event-Id: evt_5b1c...
RouterGrowth-Event-Type: email.received
RouterGrowth-Delivery-Id: whd_91aa...
t is the Unix time of the attempt. v1 is the hex HMAC-SHA256 of <t>.<raw body>, keyed with your endpoint secret: the whole whsec_... string as UTF-8 bytes, not base64-decoded. Compute it over the raw bytes you received (re-serialized JSON does not match), compare in constant time, and refuse a t more than five minutes old. A test event carries no RouterGrowth-Delivery-Id.
import hashlib, hmac, time
def authentic(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300
Retries
Answer with any 2xx within 10 seconds; do the work after answering. Anything else, a timeout included, is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours, then the delivery is marked failed. Redirects are not followed. A retry carries the same RouterGrowth-Event-Id and RouterGrowth-Delivery-Id with a new signature: use the event id to ignore an event you already handled.
An endpoint that fails every delivery for 3 days is switched off, with the reason in disabled_reason; its pending retries stop, and events that arrive while it is off are not queued for it. Fix it, check with the test call, then PATCH {"enabled": true}. Nothing is lost in the meantime: every event stays on GET /v1/events for 30 days, so you can catch up from your last RouterGrowth-Event-Id.
Reading this as an agent? This page as markdown: /docs/api/webhooks.md · every page: /docs/llms.txt