Webhook events
Get what happens in MOST POSTed to your own URL
Add an endpoint in Settings → General → Webhooks (or with the create_webhook_endpoint tool / POST /api/v1/webhooks). Pick the events you want, or leave the list empty to get all of them. Every event is a JSON POST:
POST https://your-app.com/webhooks/most
Content-Type: application/json
User-Agent: MOST-Webhooks/1
X-Most-Event: contact.opted_out
X-Most-Delivery: 6f1e… # unique per delivery (= body.id)
X-Most-Timestamp: 1782942000
X-Most-Signature-256: t=1782942000,v1=5c1d… # see "Verify" below
X-Most-Signature: 9a3b… # legacy: HMAC-SHA256(body), hex
{
"id": "6f1e…",
"event": "contact.opted_out",
"created_at": "2026-07-01T21:40:00.000Z",
"data": { "contact_id": "c1a2…", "channel": "sms", "source": "keyword_stop", "previous_status": "unknown", "captured_at": "…" }
}Events
message.received— An inbound SMS.message.replied— An inbound SMS or email from a contact you messaged on that channel in the last 30 days. Includes in_reply_to.email.received— An inbound email to your brand address.message.sent / message.delivered / message.failed— The lifecycle of a message you sent.contact.opted_out / contact.opted_in— A contact’s consent changed: STOP / START, the unsubscribe link, a bounce or complaint, a site form opt-in.email.bounced / email.complained— An email you sent bounced, or was marked as spam.link.clicked— A person clicked a tracked short link (bots and link previews never fire it).call.completed— A voice call ended.approval.decided— An owner/admin approved or rejected an agent’s action.social.post.*— approved, rejected, published, failed, needs_action.test.ping— Sent by the test button / send_test_webhook.
dm.received and the ad.* events are reserved: you can subscribe now, and they start firing when those features launch.
Verify the signature
X-Most-Signature-256 is t=<unix seconds>,v1=<hex>, where the hex is HMAC-SHA256 of "<t>.<raw body>" with your endpoint’s signing secret. Check it against the raw body (before JSON parsing), compare in constant time, and reject a timestamp more than 5 minutes from now. That stops replays.
import crypto from 'crypto'
export function verifyMostWebhook(secret, header, rawBody, toleranceSec = 300) {
if (!header) return false
const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')))
const t = Number(parts.t)
if (!t || !parts.v1) return false
if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')
const a = Buffer.from(parts.v1, 'hex'), b = Buffer.from(expected, 'hex')
return a.length === b.length && crypto.timingSafeEqual(a, b)
}
// Express: app.post('/webhooks/most', express.raw({ type: 'application/json' }), (req, res) => {
// if (!verifyMostWebhook(SECRET, req.get('X-Most-Signature-256'), req.body.toString('utf8'))) return res.sendStatus(401)
// ...; res.sendStatus(200)
// })The legacy X-Most-Signature (HMAC of the body alone, no timestamp) is still sent, unchanged, so existing receivers keep working. Move to X-Most-Signature-256 when you can.
Retries, failures and redelivery
- Answer with a
2xxwithin 8 seconds. Redirects are not followed. - A 5xx, 408, 429, timeout or network error is retried 8 times, after 30s, 2m, 10m, 30m, 1h, 3h, 6h and 12h (about a day in all). On a 429 we wait for your
Retry-Afterinstead. - Any other 4xx means you rejected the request: it is marked failed and not retried.
- Each delivery keeps the same
idacross retries; use it to drop duplicates. After 15 deliveries in a row fail for good, the endpoint is disabled. Turn it back on in Settings. - Settings shows each endpoint’s recent deliveries (kept 30 days) with status, HTTP code and a Redeliver button. A redelivery sends the same event and payload again under a new delivery id.
API
With an API key (Settings → API keys):
GET /api/v1/webhooks # webhooks:read (never returns secrets)
POST /api/v1/webhooks {url, events?, description?} # webhooks:write, owner/admin approval
DELETE /api/v1/webhooks/{id} # webhooks:write, owner/admin approval
GET /api/v1/webhooks/{id}/deliveries?status&limit # webhooks:read
POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver # webhooks:write
POST /api/v1/webhooks/{id}/test # webhooks:writeWrites need an Idempotency-Key header. A new endpoint’s signing secret is returned once, in the result of the approved create, and never listed.