Webhook events
Webhook envelope, headers, signature verification, retries, and the payload of each public event.
Rotor sends a signed POST with a JSON body to each endpoint you register for an event. This page is generated from the schemas Rotor tests its payloads against.
- Payloads are not versioned: they do not depend on the
Rotor-Versionof your API key. - Delivery is at least once. Ignore an event whose
idyou already handled; the sameidis sent on every retry and to every endpoint. Order is not guaranteed. - Reply with a
2xxquickly. Process the event after you reply.
Envelope
Every event has this body.
Headers
Verifying the signature
v1 is the hex HMAC-SHA256 of "<t>.<raw body>" with your endpoint's signing secret. t is the time of that attempt, so each retry has a new t and v1.
- Read
tandv1fromx-rotor-signature. - Build
"<t>.<raw body>"from the raw request body exactly as received. Do not re-serialize parsed JSON. - Compute the HMAC-SHA256 with your secret and hex-encode it.
- Compare with
v1in constant time. - Reject if
tis more than five minutes old.
const crypto = require('crypto')
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')))
if (!parts.t || !parts.v1) return false
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.${rawBody}`)
.digest('hex')
const a = Buffer.from(expected)
const b = Buffer.from(parts.v1)
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false
return Math.abs(Date.now() / 1000 - Number(parts.t)) < 300
}Retries and disabling
- A delivery succeeds on any
2xxreply within 10 seconds. Another status, a redirect (never followed), no reply, or a timeout is a failed attempt. - Up to 6 attempts. Retries wait 1 minute, 10 minutes, 60 minutes, 6 hours and 16 hours after the previous failed attempt. A retry can be up to a minute late.
- After the sixth failed attempt the delivery is failed and is not sent again.
- An endpoint that has failed continuously for 3 days, with a delivery failing in the last 24 hours, is disabled and Rotor emails the company's owners and admins. Re-enable it after fixing the receiver. Events are not replayed for a disabled endpoint.
message.received
An inbound SMS arrived. data.message.direction is inbound and status is received.
The payload is data.message.
{
"id": "4c1d8a52-7e30-4b9f-a6d1-2f8e0b93c571",
"type": "message.received",
"created_at": "2026-10-28T15:30:12.204Z",
"company_id": "753957fe-5aa5-44b1-a3f0-cc16d5a8caa9",
"data": {
"message": {
"id": "9f3c0a1e-4d2b-4c88-9a71-6e0b2f5d8a33",
"created_at": "2026-10-28T15:30:11.912Z",
"direction": "inbound",
"channel": "sms",
"status": "received",
"content": "Can you come Thursday instead?",
"from_number": "+15125559876",
"to_number": "+15125550101",
"contact": {
"type": "customer",
"id": "7b1e2f44-9c3a-4a5d-8f01-2c9d7e4b6a10",
"name": "Dana Whitfield",
"phone": "+15125559876"
},
"attachments": [],
"provider_message_id": "SM0123456789abcdef0123456789abcdef",
"errors": [],
"source": null,
"read": false
}
}
}job.completed
A job was set to Completed.
The payload is data.job.
{
"id": "6f0e3b52-8d17-4c9a-b4a2-1e7d95c0a384",
"type": "job.completed",
"created_at": "2026-10-28T15:41:09.311Z",
"company_id": "753957fe-5aa5-44b1-a3f0-cc16d5a8caa9",
"data": {
"job": {
"id": "d2a97e14-0b6c-4f35-8a51-c9e3f7b20d68",
"customer_id": "9b4c1f70-3e2a-4d85-a6c9-5f08e1d7a213",
"status": "Completed",
"total": 180.5,
"completed_at": "2026-10-28T15:41:08.902Z"
}
}
}Still need help? Ask the team