Skip to main content

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-Version of your API key.
  • Delivery is at least once. Ignore an event whose id you already handled; the same id is sent on every retry and to every endpoint. Order is not guaranteed.
  • Reply with a 2xx quickly. Process the event after you reply.

Envelope

Every event has this body.

FieldTypeNullableDescription
idstring (UUID)noEvent ID. Use it to deduplicate.
typestringnoEvent name, e.g. message.received.
created_atstring (ISO 8601)noWhen Rotor built the event.
company_idstring (UUID)noThe company the event belongs to.
dataobjectnoOne key holding the event payload; the key is named in each event below.

Headers

HeaderValue
content-typeapplication/json
x-rotor-eventThe event name.
x-rotor-event-idThe event ID, same as the body id.
x-rotor-delivery-attempt1 for the first try, up to 6.
x-rotor-signaturet=<unix seconds>,v1=<signature>

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.

  1. Read t and v1 from x-rotor-signature.
  2. Build "<t>.<raw body>" from the raw request body exactly as received. Do not re-serialize parsed JSON.
  3. Compute the HMAC-SHA256 with your secret and hex-encode it.
  4. Compare with v1 in constant time.
  5. Reject if t is 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 2xx reply 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.

FieldTypeNullableDescription
data.message.idstringnoMessage ID (UUID).
data.message.created_atstringnoWhen the message was created (ISO 8601).
data.message.directionenum: inbound, outboundnoinbound (from the contact) or outbound (from the company).
data.message.channelstringnoMessage channel, e.g. sms.
data.message.statusstringnoDelivery status. received for inbound messages.
data.message.contentstringyesMessage text; null when empty.
data.message.from_numberstringyesSender number. Outbound: the company number; inbound: the contact.
data.message.to_numberstringyesRecipient number. Outbound: the contact; inbound: the company number.
data.message.contactobjectyesnull when the sender could not be matched to a lead or customer.
data.message.contact.typestringnolead or customer.
data.message.contact.idstringnoLead or customer ID (UUID).
data.message.contact.namestringyesContact name.
data.message.contact.phonestringyesContact phone number.
data.message.attachmentsarray of objectnoMMS media; empty array when none.
data.message.attachments[].namestringnoFile name; may be empty.
data.message.attachments[].urlstringnoStored media URL.
data.message.attachments[].typestringnoContent type, for example image/jpeg; may be empty.
data.message.attachments[].sizenumbernoSize in bytes; 0 when unknown.
data.message.provider_message_idstringyesThe carrier's message ID, stable for correlating with delivery events.
data.message.errorsarray of stringnoFailure reasons; empty unless status is failed.
data.message.sourcestringyesprivate_api or public_api for messages sent through those APIs, otherwise null.
data.message.readbooleannoPer-message read state. Inbound messages start false.
{
  "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.

FieldTypeNullableDescription
data.job.idstringnoJob ID (UUID).
data.job.customer_idstringyesCustomer the job belongs to (UUID).
data.job.statusstringyesJob status; Completed for this event.
data.job.totalnumberyesJob total as a number.
data.job.completed_atstringyesWhen the job was completed (ISO 8601).
{
  "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"
    }
  }
}