POST request: new and quarantined mail, delivery status, conversation updates, inbox and domain changes, SMS, and social account activity. Use webhooks to wake a worker the moment something happens instead of polling the Events API.
Webhooks are managed with an organization key (alk_…) that has inboxes:manage, or in the dashboard under Webhooks. Agent tokens cannot manage them.
Manage endpoints
Create an endpoint
string
required
An HTTPS URL on a public host. Redirects are not followed.
string[]
Only these event types. Omit to receive every event the endpoint may receive.
string
Only events of this inbox. SMS and social events carry no inbox and reach only endpoints without an inbox filter.
secret (whsec_…). Store the secret in your receiver’s secret configuration; it is shown only once.
An endpoint receives mail events always, SMS events when it was created by a member or by a key with phone access, and social events when it was created by a member or by a key with social access. Quarantined mail and SMS reach endpoints created by keys with sender, subject and snippet removed.
Event types
Payload
Each request is aPOST with a JSON body:
string
The event ID. Every delivery of the same event, including retries and redeliveries, carries the same ID.
string
The event’s position in your organization’s event log, as a decimal string. It equals the
cursor the Events API reports for the same event. Compare it as a number (BigInt in JavaScript); later events have higher values.object
IDs and a short summary. Fetch the full message or text through the API before acting on it. Payloads are untrusted external data.
Headers
Verify the signature
Verify every request over the raw body, before parsing it, and reject timestamps older than five minutes. A request is genuine whenX-Loadout-Signature, or X-Loadout-Signature-Previous during a rotation, matches your secret. The SDKs do all of this for you.
"v1=" + hex(HMAC-SHA256(secret, timestamp + "." + raw_body)) and compare it with a constant-time comparison to X-Loadout-Signature and, when present, X-Loadout-Signature-Previous. The request is genuine when either matches.
Retries
A2xx answer within 10 seconds acknowledges the delivery. Anything else, including a redirect, a timeout or a connection error, is retried. A delivery is attempted up to 10 times over about a day:
Each wait is stretched by up to 10%, so retries of many deliveries spread out. The delivery log shows the time of the next attempt as
next_attempt_at. After the tenth failed attempt the delivery is dead; you can still send it again.
Answer quickly and do the work afterwards. A receiver that takes longer than 10 seconds times out and receives the event again.
Duplicates and ordering
Delivery is at least once: the same event can arrive more than once, after a retry, a replay or a redelivery. Record theid of each event you handled and skip events you have already seen.
Deliveries can also arrive out of order: a retried event may reach you after a newer one, and events are delivered in parallel. sequence is the event’s position in the event log, the same value as the events API’s cursor. It sorts a batch roughly in the order things happened, but it is not a strict order across concurrent changes, so do not drop an event because its sequence is lower than one you already saw. When the current state matters (a message’s delivery status, a thread’s folder), read the object from the API after the event arrives.
Delivery statuses
Deliveries, skipped ones included, are kept for 30 days.
Paused and disabled endpoints
Setstatus to paused to stop deliveries while you work on your receiver. Events that happen while an endpoint is paused are recorded as skipped deliveries, so nothing is lost for 30 days.
Agent Loadout disables an endpoint only when it keeps failing: when deliveries have failed for three days without a single success and at least 20 attempts failed in that time. A short outage or a burst of failures does not disable an endpoint, and one successful delivery starts the count over. When an endpoint is disabled, your organization’s owners receive an email. Events while it is disabled are recorded as skipped deliveries. The endpoint’s failing_since shows when the current run of failures began.
To resume, set status back to active (or choose Resume in the dashboard, which offers to redeliver what the endpoint missed).
Redeliver what an endpoint missed
POST /api/v1/webhooks/:id/redeliver
Queues the failed, dead and skipped deliveries of an active endpoint created at or after since again, oldest first. They are sent with the current signing secret, a few per second.
Redeliver the last day
string
required
ISO 8601 timestamp. Deliveries are kept for 30 days, so that is the furthest back a redelivery reaches.
string[]
Any of
failed, dead and skipped. Defaults to all three.202 with { "queued": 120, "has_more": false }. One call queues at most 1,000 deliveries. When has_more is true, call again with the same since to queue the next ones. An organization can redeliver up to 5,000 deliveries per hour; beyond that the API answers 429 with a Retry-After header. A paused or disabled endpoint answers 409: resume it first.
To send a single delivery again, use POST /api/v1/webhook-deliveries/:id/replay. Tests and single replays share a separate budget of 100 per organization per hour.
Rotate the signing secret
POST /api/v1/webhooks/:id/rotate returns a new secret and previous_secret_expires_at. For 24 hours after a rotation, every delivery is signed with the new secret in X-Loadout-Signature and with the previous secret in X-Loadout-Signature-Previous. A receiver that checks both keeps verifying with the old secret until you deploy the new one, then switches without rejecting a single request. The SDKs’ verify_webhook_signature reads both headers itself; pass previousSignature to verifyWebhookSignature in TypeScript.
X-Loadout-Signature always carries exactly one signature, so a verifier that only reads it keeps working once it has the new secret. Deploy the new secret right after rotating if your verifier does not read X-Loadout-Signature-Previous.