API docs

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 2xx within 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-After instead.
  • Any other 4xx means you rejected the request: it is marked failed and not retried.
  • Each delivery keeps the same id across 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:write

Writes need an Idempotency-Key header. A new endpoint’s signing secret is returned once, in the result of the approved create, and never listed.