Consent webhooks
An owner adds a webhook URL under Settings, Webhooks, and copies its signing secret (whsec_…), which is shown once. Ringmaster then posts every consent change as JSON:
| type | When |
|---|
profile.unsubscribed | The person turned a topic off, or your app withdrew an opt-in subscription. |
profile.resubscribed | A suppression was lifted: by the person on their preference page, by your app, or in the console. |
profile.subscribed | Your app recorded opt-in consent. |
profile.suppressed | Your app or someone in the console suppressed the address, or it hard-bounced or drew a spam complaint. |
{
"id": "0f8a2c7e-5b1d-4e3a-9c6f-2d4b8e1a7c90",
"type": "profile.unsubscribed",
"occurredAt": "2026-10-29T12:00:00.000Z",
"org": "6b1e3f0a-9d2c-4b7e-8a5f-1c3d5e7f9a2b",
"email": "jane@example.com",
"topic": "product-news",
"reason": "unsubscribe_link"
}topic is the topic's key, or null for every topic. reason says who made the change: unsubscribe_link the person, through an email link or their preference page; api your app, through this API; admin someone in the console; bounce and complaint the person's mail provider. Skip api events if your app already knows about them.
Each request carries Ringmaster-Event-Id, the same as the body's id, and Ringmaster-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>, signed over <t>.<raw body> with the webhook's secret. Verify it against the raw body before you parse it, and refuse a timestamp more than 5 minutes old:
import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody is the request body exactly as received, before any JSON parsing.
function verifyRingmasterSignature(secret, rawBody, header, toleranceSeconds = 300) {
const parts = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
const timestamp = Number(parts.t);
if (!Number.isInteger(timestamp) || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
const received = Buffer.from(parts.v1, "hex");
return received.length === expected.length && timingSafeEqual(received, expected);
}Answer any 2xx within 10 seconds. Anything else, a timeout or a redirect is retried after 30 seconds, then after a wait that doubles up to an hour, until 24 hours after the event; then it is marked failed in the console. A delivery can arrive more than once, so skip a Ringmaster-Event-Id you have handled.
Endpoints
POST /v1/events
Track events. Records one event, or up to 100 as { events: [...] }. Each event creates or updates its profile first, merging properties key by key. Flows read the events of one request in the order you send them.
Answers 202. Stored.
const response = await fetch(`${RINGMASTER_URL}/v1/events`, {
method: "POST",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": outboxRow.id,
},
body: JSON.stringify({
"event": "register",
"profile": {
"id": "user_8f2c",
"email": "jane@example.com",
"phone": "+14155550123",
"properties": {
"first_name": "Jane",
"wedding_date": "2027-06-12"
},
"country": "US",
"timezone": "America/New_York"
},
"properties": {
"source": "signup_form"
},
"occurredAt": "2026-10-29T12:00:00Z"
}),
});PUT /v1/profiles/{id}
Create or update a profile. Creates the profile with your id, or updates it. Fields you leave out keep their stored value.
Answers 200. Stored.
const response = await fetch(`${RINGMASTER_URL}/v1/profiles/${encodeURIComponent("user_8f2c")}`, {
method: "PUT",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": outboxRow.id,
},
body: JSON.stringify({
"email": "jane@example.com",
"properties": {
"plan": "free"
}
}),
});DELETE /v1/profiles/{id}
Erase a profile. Deletes the profile and everything Ringmaster holds about it, for a GDPR erasure request, including the opt-in records of its email and phone. The audit log records the erasure without the email. Suppressions and SMS opt-outs stay, because they are keyed by email and phone.
Answers 200. Erased, or there was nothing to erase.
const response = await fetch(`${RINGMASTER_URL}/v1/profiles/${encodeURIComponent("user_8f2c")}`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Idempotency-Key": outboxRow.id,
},
});POST /v1/suppressions
Suppress an email address. Stops Ringmaster mailing the address in one topic or, with no topic, in every opt-out and opt-in topic. Use it when the person unsubscribes elsewhere. A service topic cannot be suppressed: only a bounce or a complaint stops one.
Answers 200. Suppressed. created is false when this suppression was already there.
const response = await fetch(`${RINGMASTER_URL}/v1/suppressions`, {
method: "POST",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": outboxRow.id,
},
body: JSON.stringify({
"email": "jane@example.com"
}),
});DELETE /v1/suppressions/{email}
Lift a suppression. Removes the unsubscribes your app or the person made for the address and topic, or the every-topic ones with no topic. Suppressions made in the console, bounces and complaints stay. URL-encode the address.
Answers 200. Lifted, or there was nothing to lift.
const response = await fetch(`${RINGMASTER_URL}/v1/suppressions/${encodeURIComponent("jane@example.com")}`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Idempotency-Key": outboxRow.id,
},
});POST /v1/subscriptions
Record opt-in consent. Records that the person agreed to an opt-in topic, with the evidence you collected. An opt-in topic mails only subscribers. A suppression still stops the topic; lift it as well when the new consent should override it. A repeat keeps the first record. A new subscription whose consentedAt is within the last day enrolls each profile with the address in the flows that start on subscribing to the topic, so send the profile first; an older one is treated as a backfill and enrolls no one. With confirm true, on a topic with double opt-in on, Ringmaster holds the subscription and emails the person a link to confirm it. Nothing is subscribed, and no flow starts, until they confirm; the link works for 7 days, and a repeat within an hour sends no second email. An address that is suppressed or already subscribed gets no email. While the organization has no verified sending domain that carries marketing mail, a request with confirm true on such a topic that would email a confirmation is refused with 422 cannot_confirm and nothing is recorded; one for an address already subscribed or suppressed answers as ever.
Answers 200. Recorded, or held for confirmation. created is false when nothing new was subscribed; pending is true when the person must confirm from their inbox.
const response = await fetch(`${RINGMASTER_URL}/v1/subscriptions`, {
method: "POST",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": outboxRow.id,
},
body: JSON.stringify({
"email": "jane@example.com",
"topic": "newsletter",
"source": "signup_form",
"consentedAt": "2026-10-29T12:00:00Z",
"ip": "203.0.113.7",
"userAgent": "Mozilla/5.0"
}),
});DELETE /v1/subscriptions/{email}
Withdraw opt-in consent. Removes the person's subscription to an opt-in topic. URL-encode the address.
Answers 200. Removed, or there was nothing to remove.
const response = await fetch(`${RINGMASTER_URL}/v1/subscriptions/${encodeURIComponent("jane@example.com")}?topic=newsletter`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Idempotency-Key": outboxRow.id,
},
});POST /v1/sms-subscriptions
Record SMS opt-in consent. Records that the person agreed to marketing texts at this number, with the evidence you collected. Email consent never covers texts: a flow's SMS step in a topic that is not a service topic texts only a subscribed number, and skips the step for anyone else. A number that texted STOP, or that Twilio refused as unsubscribed, stays opted out until it texts START, because Twilio blocks it until then; this endpoint does not lift that. A repeat keeps the first record.
Answers 200. Recorded. created is false when the number was already subscribed.
const response = await fetch(`${RINGMASTER_URL}/v1/sms-subscriptions`, {
method: "POST",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": outboxRow.id,
},
body: JSON.stringify({
"phone": "+14155550123",
"source": "checkout_sms_box",
"consentedAt": "2026-10-29T12:00:00Z",
"ip": "203.0.113.7",
"userAgent": "Mozilla/5.0"
}),
});DELETE /v1/sms-subscriptions/{phone}
Withdraw SMS opt-in consent. Removes the number's consent to marketing texts. Service texts, such as order updates, still go to it until it texts STOP. URL-encode the number, so + becomes %2B.
Answers 200. Removed, or there was nothing to remove.
const response = await fetch(`${RINGMASTER_URL}/v1/sms-subscriptions/${encodeURIComponent("+14155550123")}`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Idempotency-Key": outboxRow.id,
},
});POST /v1/enrollments
Enroll a profile in a flow. Enrolls the profile in an active flow now, without waiting for its trigger event, for a one-off or a backfill. The profile is created or updated first. The flow's reentry rule and the person's consent still apply, so the answer says whether the profile was enrolled and, if not, why: already_active, reentry (the rule refused it), no_key (the flow enters per event property and properties lacks it, or resume is given for a date-triggered flow and the profile lacks the date), entry (the profile does not meet the flow's entry conditions), exclusive (the flow runs one marketing flow at a time and the profile is in another), consent_blocked, no_email, or no_phone for a flow whose steps are all texts. A flow with any email step needs the profile's email and its email consent; a flow of texts alone needs its phone and its SMS consent. The properties stand in for the trigger event's in the flow's emails. With resume, the enrollment is carried over part way through from another system, such as one moving off Klaviyo: it goes to resume.step next, due at resume.dueAt held to that step's time of day or the recipient's daytime, and counts from resume.enrolledAt. The other system already admitted the profile, so entry, exclusive and supersedes are not applied; consent and reentry are. A date-triggered flow's enrollment takes the profile's current date as its key, so the date poll never enrolls it again for that date. In a flow with splits, Ringmaster decides a split only when an enrollment reaches it, so resume.branches must name the branch the enrollment took at every split it passed before resume.step: yes or no for a conditional split, the variant's name for a random one. The enrollment keeps those branches for the rest of the flow. A 422 names the field: branch_missing when a split before resume.step has no branch, branch_unknown when resume.branches names a branch the split does not have or a split the enrollment does not pass before resume.step, and step_off_path when resume.step runs only on a branch that resume.branches does not take. A split at resume.step or after it is decided by Ringmaster when it comes due.
Answers 200. Decided.
const response = await fetch(`${RINGMASTER_URL}/v1/enrollments`, {
method: "POST",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": outboxRow.id,
},
body: JSON.stringify({
"flow": "welcome",
"profile": {
"id": "user_8f2c",
"email": "jane@example.com",
"phone": "+14155550123",
"properties": {
"first_name": "Jane",
"wedding_date": "2027-06-12"
},
"country": "US",
"timezone": "America/New_York"
},
"properties": {
"source": "backfill"
}
}),
});PUT /v1/catalog/items
Create or replace catalog items. Creates or replaces up to 100 items of your catalog, each keyed by your own id. Every field is replaced: a field you leave out is cleared. Emails show an item's title, image and price as they are when the email is sent, and leave out an item that is not available. An item that becomes available again sends its back-in-stock subscribers their flow, and one whose price falls sends its price-drop subscribers theirs. url and imageUrl must be https URLs.
Answers 200. Stored. created counts new items and updated replaced ones.
const response = await fetch(`${RINGMASTER_URL}/v1/catalog/items`, {
method: "PUT",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": outboxRow.id,
},
body: JSON.stringify({
"items": [
{
"id": "sku-1042",
"title": "Linen apron",
"description": "Stonewashed linen, one size",
"url": "https://shop.example.com/products/linen-apron",
"imageUrl": "https://cdn.example.com/linen-apron.jpg",
"price": 39,
"currency": "GBP",
"compareAtPrice": 49,
"categories": [
"kitchen"
],
"available": true,
"inventory": 12
}
]
}),
});DELETE /v1/catalog/items/{id}
Delete a catalog item. Deletes the item and every subscription to it. Emails leave it out from then on. URL-encode the id.
Answers 200. Deleted, or there was nothing to delete.
const response = await fetch(`${RINGMASTER_URL}/v1/catalog/items/${encodeURIComponent("sku-1042")}`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Idempotency-Key": outboxRow.id,
},
});POST /v1/catalog/items/{id}/subscriptions
Subscribe a profile to an item. Records that the person asked to hear about one item: back_in_stock when it becomes available again, or price_drop when it gets cheaper than it is now. The profile is created or updated first. When the item changes, the person enters each active flow whose trigger is that catalog change, once for that change, with the item as the event its emails read. A back-in-stock subscription ends once it fires; a price-drop one stays for later drops. It is a request for one message about one item, so it needs no topic subscription beyond what the flow's topic requires. A repeat keeps the first request. URL-encode the id.
Answers 200. Recorded. created is false when the profile had already asked.
const response = await fetch(`${RINGMASTER_URL}/v1/catalog/items/${encodeURIComponent("sku-1042")}/subscriptions`, {
method: "POST",
headers: {
Authorization: `Bearer ${RINGMASTER_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": outboxRow.id,
},
body: JSON.stringify({
"kind": "back_in_stock",
"profile": {
"id": "user_8f2c",
"email": "jane@example.com"
}
}),
});