Quickstart

relaybell adds web push notifications to any website. Drop in a snippet, and you can collect subscribers and send notifications — with automation, targeting, and analytics — in minutes.

Grab your Project ID from your dashboard (Install page). On WordPress, use the plugin instead — it does steps 1 and 2 for you.

1. Add the snippet to every page, just before </body>:

<script src="https://relaybell.com/relaybell-sdk.js"></script>
<script>
  RelayBell.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" });
</script>

2. Host the service worker. Download sw.js and upload it to the root of your site, so it opens at https://yoursite.com/sw.js. Browsers only run a service worker from your own domain, so push can't work without this file. (Can't put it at the root? See Installing the SDK.)

3. Send. relaybell now shows your opt-in prompt, subscribes visitors and stores them. To send from your server, create an API key under Settings → Developer → API keys and POST to the REST API (see Sending) — or send from the dashboard.

Installing the SDK

The SDK needs a service worker on your own domain. The default swPath is /sw.js — host our sw.js there, or put it somewhere else on the same domain and pass that path as swPath (for example "/folder/sw.js"). The WordPress plugin serves its own service worker, so there's no file to upload. Shopify doesn't let you upload this file — see Shopify.

apiBase is the relaybell address the SDK talks to. If you leave it out, the SDK uses the address it was loaded from — https://relaybell.com for the snippet above — so the snippet works either way.

Browser SDK — init & options

RelayBell.init({
  projectId: "YOUR_PROJECT_ID",   // required
  apiBase:   "https://relaybell.com", // optional: defaults to where relaybell-sdk.js was loaded from
  swPath:    "/sw.js",            // service-worker path on your domain
  externalId: "user_123",         // link this browser to your own user id
  userHash: "9f2c…",              // your server's signature of externalId (see Identity verification)
  tags: { plan: "pro" },          // custom attributes for segmentation
  requireConsent: false,          // true = wait for grantConsent() (CMP integration)
  policyVersion: "2026-01"        // recorded with consent for your audit trail
});

Browser SDK — methods

// Behavioral tracking → powers cart abandonment, product alerts, attribution
RelayBell.track("cart.updated", { productId: "1234", product: "Blue Shoes", price: 49, url: location.href });
RelayBell.trackConversion(79.99, { orderId: "A123" });

Opt-in prompts

Prompt style, copy, trigger and colors are configured per project — in the dashboard under Audience → Subscribe prompt (with a live preview), or with PUT /api/v1/prompt. Styles: slidein (default), bar, modal, native. Triggers: delay, load, click, scroll, exit (desktop only). Add a privacy policy link in Settings → Privacy (it's the privacyUrl setting, not a prompt field) to show it on the prompt. Set a prompt b variant to A/B-test opt-in copy. Visitors who click the “no” button (or click outside a modal) aren't asked again for 7 days.

curl -X PUT https://relaybell.com/api/v1/prompt \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "prompt": { "type": "slidein", "trigger": "delay", "delaySeconds": 5,
        "title": "Stay in the loop", "message": "Get notified about offers.",
        "allowText": "Allow", "denyText": "No thanks",
        "position": "bottom-right", "accentColor": "#0B7C93" } }'

PUT /api/v1/prompt accepts the fields listed above only — anything else is dropped — and it replaces the whole prompt, so send every field you want to keep (GET /api/v1/prompt returns the current one).

Preview: open any page of your site with ?rb_preview_prompt=1 (e.g. https://yoursite.com/?rb_preview_prompt=1). The SDK removes the parameter from the address bar and shows your saved prompt (version A, in a browser that supports push) straight away — ignoring enabled, the 7-day dismissal, the current permission and the trigger. Clicking “no” in preview doesn't record a dismissal. For type: "native" it shows the slide-in card instead, since the browser's own prompt can't be previewed. The dashboard's See it on my website link does exactly this.

REST API — authentication

All server-side calls use a Bearer API key (starts with rb_live_):

curl https://relaybell.com/api/v1/stats \
  -H "Authorization: Bearer rb_live_xxxxx"

Create keys in the dashboard under Settings → Developers → API keys. A key is shown once, when you create it; relaybell stores only a hash. Keep keys on your server — never put one in code that runs in a visitor's browser (the browser SDK needs only your project ID).

API keys & scopes

Each key has a name, a list of scopes (what it may do) and an optional expiry date. Pick Full access, Send only, or any mix of the scopes below. Keys made before scopes existed have full access.

Reading your website's stats, reports, settings and notifications works with any valid key (a key without full or settings:write doesn't get the Shopify signing secret back from GET /api/v1/settings). A call the key isn't allowed to make answers 403 { "error": "insufficient_scope", "required": "<scope>" }; a key past its expiry date answers 401 api_key_expired. Only the signed-in owner creates and revokes keys; a key can revoke itself with DELETE /api/v1/keys/current.

The WordPress plugin gets its own key when you connect a site, with send and events:write only: enough for publish notifications, WooCommerce events, test sends and user ID verification, but it can't download your subscribers.

Identity verification

Stops someone pretending to be one of your users to get their notifications.

The browser SDK tells relaybell who a visitor is with externalId (your own user id, often an email). That call is public, so without a check anyone could send your customer's externalId from their own browser and start receiving that customer's notifications — cart reminders, order updates and anything else you send to that id. With identity verification, your server signs each externalId with a secret key that only you and relaybell know, and relaybell only accepts an externalId whose signature is correct.

Turn it on: in the dashboard, Settings → Developer → User ID verification shows your secret key and a Require verified User IDs switch. Start sending userHash first, then switch it on. The WordPress plugin (1.2.4 or newer) does all of this automatically, and the Shopify code on the dashboard's Install page includes the signature.

The signature (userHash)

userHash = lowercase hex HMAC-SHA256, where the key is your secret key — the 64-character hex string, used as plain text (don't hex-decode it) — and the message is the externalId exactly as you send it (numbers as their text form, e.g. 42 → "42"). relaybell compares it without regard to upper/lower case. Make it on your server — never put the secret key in code that runs in the browser.

// Node.js
const crypto = require("crypto");
const userHash = crypto.createHmac("sha256", IDENTITY_SECRET).update(String(externalId)).digest("hex");
// or, with the Node SDK: const { userHash } = require("relaybell"); userHash(IDENTITY_SECRET, externalId)

<?php // PHP
$userHash = hash_hmac('sha256', (string) $externalId, $identitySecret);
// or, with the PHP SDK: Relaybell\Client::userHash($identitySecret, (string) $externalId)

# Python
import hmac, hashlib
user_hash = hmac.new(IDENTITY_SECRET.encode(), str(external_id).encode(), hashlib.sha256).hexdigest()
# or, with the Python SDK (1.1.0 or newer): from relaybell import user_hash; user_hash(IDENTITY_SECRET, external_id)

On Shopify, Liquid runs on Shopify's servers, so the key can go in your theme without reaching the page:

{{ customer.email | hmac_sha256: 'YOUR_SECRET_KEY' }}

Pass it to the browser SDK

RelayBell.init({
  projectId: "YOUR_PROJECT_ID",
  apiBase: "https://relaybell.com",
  externalId: "jane@example.com",
  userHash: "<signature made on your server>"
});

// or later, e.g. once the visitor signs in:
RelayBell.identify("jane@example.com", "<signature made on your server>");

The SDK sends userHash wherever it sends externalId. If relaybell answers that the id wasn't verified, the SDK logs one console warning: relaybell: the User ID was not verified — check userHash.

What relaybell does with it

This applies to the public routes the browser SDK uses: POST /api/v1/projects/:id/subscriptions (body fields externalId, userHash; the identity field is left out when no externalId was sent) and POST /api/v1/projects/:id/events (an event's user id is stored only when its userHash is valid, or when no hash is sent and verification isn't required). Calls made with your API key — such as POST /api/v1/events from your server — are already trusted and don't need userHash.

Managing the secret key

curl https://relaybell.com/api/v1/identity -H "Authorization: Bearer rb_live_xxxxx"

curl -X PUT https://relaybell.com/api/v1/identity \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "required": true }'

Sending notifications

POST /api/v1/notifications — accepts the send and answers 202; delivery happens in the background. With no targeting fields it goes to every subscriber of the website the API key belongs to. Until the account's email address is verified it answers 403 email_not_verified (test sends to your own test devices still work).

curl -X POST https://relaybell.com/api/v1/notifications \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "title": "Flash sale 🔥",
    "body": "30% off ends tonight — {name|there}!",
    "url": "https://shop.example/sale"
  }'

Response (202):

{ "ok": true, "notificationId": "5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42", "status": "queued" }

status is "queued" when sending starts now, or "scheduled" when it waits — for a future sendAt, or because your quiet hours are on (the send is held until they end). Keep notificationId: it is how the send appears in /stats and in webhooks, and how you cancel it.

Send to one user

First link the browser to your user: pass your own user id as externalId in RelayBell.init(), or call RelayBell.identify(externalId) once the visitor signs in (with userHash if you use identity verification). Then send with that id from your server. If no subscribed browser has the id, the send still answers 202 and simply reaches nobody.

curl -X POST https://relaybell.com/api/v1/notifications \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "transactional": true,
    "title": "Your order has shipped",
    "body": "Order #1042 is on its way.",
    "url": "https://shop.example/orders/1042"
  }'

// Node.js (npm install relaybell)
const { RelayBell } = require("relaybell");
const rb = new RelayBell({ apiKey: process.env.RELAYBELL_API_KEY });
const { notificationId } = await rb.send({
  externalId: "user_123",
  transactional: true,
  title: "Your order has shipped",
  body: "Order #1042 is on its way.",
  url: "https://shop.example/orders/1042",
});

# Python (pip install relaybell)
import os
from relaybell import RelayBell
rb = RelayBell(os.environ["RELAYBELL_API_KEY"])
res = rb.send(
    externalId="user_123",
    transactional=True,
    title="Your order has shipped",
    body="Order #1042 is on its way.",
    url="https://shop.example/orders/1042",
)
print(res["notificationId"])

<?php // PHP (composer require relaybell/relaybell-php)
$rb = new Relaybell\Client(getenv('RELAYBELL_API_KEY'));
$res = $rb->send([
    'externalId'    => 'user_123',
    'transactional' => true,
    'title'         => 'Your order has shipped',
    'body'          => 'Order #1042 is on its way.',
    'url'           => 'https://shop.example/orders/1042',
]);
echo $res['notificationId'];

For several users at once, send "externalIds": ["user_1", "user_2"] instead.

Cancel a scheduled send

POST /api/v1/notifications/:id/cancel — stops a send that is still "scheduled" (a future sendAt, or one held for quiet hours). Answers 200 { "ok": true, "canceled": true }. A send that has already started (including a per-time-zone or smart-time send, which starts at once), has finished, was already canceled, doesn't exist or belongs to another website answers 404 { "error": "not_scheduled" }.

curl -X POST https://relaybell.com/api/v1/notifications/5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42/cancel \
  -H "Authorization: Bearer rb_live_xxxxx"

Drafts

Save a notification without sending it, change it as often as you like, then send it. A draft is never queued, never counted against the send limits, never listed in the on-site inbox and never reported to webhooks.

A notification that isn't a draft answers 409 not_a_draft to PATCH, /send and DELETE; an id that isn't one of this website's answers 404 not_found. To read a draft back, use GET /api/v1/notifications/:id: its sendBody holds the saved fields. Drafts are listed with ?status=draft.

curl -X POST https://relaybell.com/api/v1/notifications \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "draft": true, "title": "Autumn sale", "body": "Up to 30% off" }'

curl -X POST https://relaybell.com/api/v1/notifications/5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42/send \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "sendAt": "2026-11-01T09:00:00Z" }'

Events & automation

POST /api/v1/events — send a behavioral event (server-side; the browser SDK's track() does this too).

{ "event": "purchase", "externalId": "user_123", "properties": { "value": 79.99 } }

Automations (/api/v1/automations) fire a push when an event happens, with an optional delay and a cancelOn event. This powers cart abandonment (a purchase cancels the reminder), back-in-stock and price-drop (see Product alerts), and welcome-back flows. A purchase with a value is attributed as a conversion to the last notification delivered to that subscriber.

POST /api/v1/automations
{ "name":"Cart abandon", "event":"cart.updated", "delaySeconds":3600,
  "cancelOn":"purchase", "action":{ "title":"You left {product} 🛒", "url":"{url}" } }

Auto-capture behaviour. Rather than call track() by hand everywhere, opt in and relaybell records pageviews, declarative clicks and scroll for you — only for subscribed or identified visitors, so anonymous traffic makes no noise:

RelayBell.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com", autoCapture: true });
// granular: autoCapture: { pageviews: true, clicks: true, scroll: true }

// Track any click declaratively — data-rb-* become event properties:
<button data-rb-event="add_to_cart" data-rb-sku="TEE-01" data-rb-price="19.99">Add to cart</button>

Mirror events from Google Tag Manager / GA. You can't trigger push directly from Google Analytics or Meta Pixel — those are analytics and ad tools, not real-time per-user event buses, and their terms don't allow using that data to message individuals. Instead, fire the same events you already track into relaybell too, most easily via a GTM Custom HTML tag on your existing dataLayer events, then segment and automate on them here:

<script>/* GTM Custom HTML tag, fired on your event trigger.
   {{Event}} is GTM's built-in variable holding the dataLayer event name. */
if (window.RelayBell) RelayBell.track({{Event}}, {});</script>

To send details with the event, replace {} with an object built from your own Data Layer Variables, for example { productId: {{DLV - productId}} }.

Product alerts (back in stock & price drop)

A product alert is about a product, not one person: your server reports that a product is back in stock or cheaper, and relaybell sends it to everyone who showed interest in that product. It takes two parts.

1. Record interest from the browser. Call track() with the product's id while the visitor is subscribed — interest is only stored for a browser with a push subscription, so check isSubscribed() (or subscribe first):

// "Notify me when back in stock" on a sold-out product.
// For a variable product, send the selected VARIATION's id.
notifyButton.addEventListener("click", async () => {
  const r = await RelayBell.subscribeNow();               // must run from the click
  if (r.subscribed) RelayBell.track("waitlist.join", { productId: "1234" });
});

// Product page view (counts toward price-drop alerts)
RelayBell.isSubscribed().then((yes) => {
  if (yes) RelayBell.track("product.viewed", { productId: "1234" });
});

// Added to cart (counts toward price-drop alerts only for a subscribed browser)
RelayBell.track("cart.updated", { productId: "1234", product: "Blue Shoes", price: 49, url: location.href });

2. Report the product event from your server (API key). Send back_in_stock or price_drop to POST /api/v1/events with no externalId (and no subscriberId or endpoint) — an event that names a person is treated as that person's own event and is not broadcast. Only this authenticated route can broadcast; the browser's track() never does.

curl -X POST https://relaybell.com/api/v1/events \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "event": "price_drop",
        "properties": { "productId": "1234-42", "parentId": "1234", "product": "Blue Shoes",
                        "url": "https://shop.example/p/blue-shoes", "oldPrice": 59, "newPrice": 49 } }'

Nothing is sent unless you have an enabled automation for that event (Automations → Back-in-stock alerts / Price-drop alerts, or POST /api/v1/automations with "event": "back_in_stock" or "price_drop"). Its title, body and url are templates, e.g. "{product|This item} is back!". Who gets it:

• back_in_stock — everyone on the product's waitlist (waitlist.join for productId or parentId). The waitlist is consumed: each person is taken off it as the alert goes out, so they get one alert per join and a later restock doesn't alert them again. It is sent as a transactional message, so the daily frequency cap can't drop an alert someone asked for.
• price_drop — anyone on the waitlist, plus subscribers who viewed (product.viewed) or carted (cart.updated) the product in the last 30 days. This list is not consumed. Price drops are deduplicated: at most one price_drop alert per product (keyed by parentId, else productId) every 10 minutes — repeats inside that window send nothing.

For product alerts, cancelOn and oncePerSubscriber don't apply; delaySeconds and your quiet hours still do. Unsubscribed people are never included.

Drip sequences

/api/v1/sequences — multi-step journeys. Subscribers enter on subscribe or on an event, then flow through steps with per-step delays; cancelOn drops them if they convert.

POST /api/v1/sequences
{ "name":"Welcome series", "trigger":"subscribe", "cancelOn":"purchase",
  "steps":[ { "delaySeconds":0, "title":"Welcome 👋" },
            { "delaySeconds":86400, "title":"Here's how to start" },
            { "delaySeconds":604800, "title":"A little something for you" } ] }

Segments & topics

• /api/v1/segments — saved filters over country, language, url, and custom tag:KEY (ops: eq, neq, contains, exists). POST /segments/preview returns a live match count.
• /api/v1/topics — preference-center categories. Subscribers opt in via RelayBell.setTopics() / showPreferences(); target with topicId.
• GET /api/v1/subscribers/export — CSV of subscribers. POST /api/v1/subscribers/import — enrich/pre-seed by external ID with tags + topics (push tokens can't be imported across origins).

Analytics & webhooks

Stats

GET /api/v1/stats — totals for the website, plus its 20 most recent sends (newest first):

{
  "subscribers": 1280,
  "subscriberDevices": { "desktop": 830, "android": 390, "ios": 60 },
  "totals": { "sent": 5400, "clicks": 310, "ctr": 5.7, "conversions": 12, "revenue": 940.5 },
  "notifications": [
    { "id": "5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42", "title": "Flash sale 🔥", "body": "…", "url": "…",
      "status": "sent", "recipients": 1275, "sent": 1262, "failed": 3, "pruned": 10, "received": 1190,
      "clicks": 74, "conversions": 4, "revenue": 316,
      "devices": { "desktop": 820, "android": 384, "ios": 58 },
      "ab": null, "abStats": null, "error": null,
      "scheduled_at": null, "created_at": "2026-10-14T09:30:00.000Z" }
  ],
  "promptAb": null,
  "emailVerified": true,
  "sendingBlocked": false
}

Also: GET /api/v1/stats/growth?days=30 → { days, series: [{ date, subscribed, churned }], totals: { subscribed, churned, net } } (1–365 days), and GET /api/v1/stats/health → { active, reachable, unsubscribed, new30, lost30, dormant, churnRate }.

Reports & export

The numbers mean the same thing in every report: sent, pushes the browsers' push services accepted; delivered, pushes a device confirmed it received (what /stats calls received); clicked; ctr, clicked ÷ sent as a percentage with one decimal (0 when nothing was sent); conversions and revenue credited to a notification. from and to are calendar days (YYYY-MM-DD, both included) in tz: an IANA time zone such as Europe/London. Left out, tz is your website's time zone (the one its quiet hours use), or UTC.

Daily numbers

GET /api/v1/stats/timeseries?from=2026-10-01&to=2026-10-14&tz=Asia/Kolkata — one point per day (days without sends are zeros), the totals, and the same totals for the period of the same length just before. Each notification counts on the day it went out: its scheduled time, or the time it was made for a send that started straight away. Without from and to it covers the last 30 days. A range can be at most 366 days (400 invalid_range).

{
  "from": "2026-10-01", "to": "2026-10-14", "tz": "Asia/Kolkata", "interval": "day",
  "points": [
    { "date": "2026-10-01", "sent": 1262, "delivered": 1190, "clicked": 74, "conversions": 4, "revenue": 316 }
  ],
  "totals":   { "sent": 15400, "delivered": 14120, "clicked": 820, "ctr": 5.3, "conversions": 41, "revenue": 3120.5 },
  "previous": { "from": "2026-09-17", "to": "2026-09-30", "sent": 13900, "delivered": 12800, "clicked": 690, "ctr": 5, "conversions": 30, "revenue": 2210 },
  "currency": "USD"
}

currency is the revenue currency set for the website, or null.

List of notifications

GET /api/v1/notifications?from&to&status&q&limit&cursor — newest first, 25 per page (limit up to 100). status is one or more of draft, scheduled, queued, sending, sent, failed and canceled, separated by commas; without it, everything except drafts is listed. q searches titles and texts, in any case. from and to filter on the day a notification was made. For the next page, send the nextCursor you got as cursor, with the same filters; it is null on the last page. Pages don't shift when new sends arrive.

{
  "items": [
    { "id": "5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42", "title": "Flash sale 🔥", "body": "…", "status": "sent",
      "created_at": "2026-10-14T09:30:00.000Z", "scheduled_at": null,
      "recipients": 1275, "sent": 1262, "delivered": 1190, "failed": 3, "pruned": 10,
      "clicked": 74, "ctr": 5.9, "conversions": 4, "revenue": 316,
      "ab": false, "targetSummary": "VIP buyers · Topic: Deals", "automation": false, "error": null }
  ],
  "nextCursor": "WyIyMDI2LTEwLTE0VDA5OjMwOjAwLjAwMDAwMFoiLCI1YjBj…"
}

A bad filter answers 400 with invalid_status, invalid_range, invalid_tz or invalid_cursor.

One notification

GET /api/v1/notifications/:id — everything stored about one notification, and how it did. An id that isn't one of this website's answers 404 not_found.

{
  "notification": { "id": "5b0c2f7e-…", "title": "Flash sale 🔥", "status": "sent", "target": { "segmentId": "…" },
                    "targetSummary": "VIP buyers", "ab": null, "ab_test": null, "translations": null, "actions": null,
                    "image": null, "url": "https://shop.example/sale", "ttl": null, "scheduled_at": null, "stats": { … },
                    "sent": 1262, "delivered": 1190, "clicked": 74, "ctr": 5.9, … },
  "funnel":    { "recipients": 1275, "sent": 1262, "delivered": 1190, "clicked": 74, "converted": 4, "failed": 3, "expired": 10 },
  "devices":   [ { "device": "desktop", "sent": 820, "clicked": 51 } ],
  "variants":  [],
  "languages": [ { "language": "en", "sent": 900, "clicked": 55 } ],
  "errors":    [ { "code": "expired", "count": 10 }, { "code": "timeout", "count": 3 } ],
  "revenue": 316, "currency": "USD",
  "sendBody": { "title": "Flash sale 🔥", "url": "https://shop.example/sale", "segmentId": "…" }
}

Export to CSV

GET /api/v1/notifications/export.csv — the same filters as the list (no cursor), the same rows in the same order, up to 10,000 of them. Columns: id, created_at, scheduled_at, status, title, target, recipients, sent, failed, clicked, ctr, conversions, revenue, where target is the targetSummary. A title that starts with =, +, - or @ gets a leading ', so a spreadsheet doesn't run it as a formula.

curl "https://relaybell.com/api/v1/notifications/export.csv?from=2026-10-01&to=2026-10-14&status=sent" \
  -H "Authorization: Bearer rb_live_xxxxx" -o notifications.csv

Webhooks

relaybell can tell your own server when something happens. Add a webhook in Settings → Developer → Webhooks, or with the API:

curl -X POST https://relaybell.com/api/v1/webhooks \
  -H "Authorization: Bearer rb_live_xxxxx" -H "Content-Type: application/json" \
  -d '{ "url": "https://yourapp.example/webhooks/relaybell", "events": ["notification.clicked"] }'

It answers 201 { "webhook": { "id", "url", "events", "secret", "enabled", "created_at" } }. The secret (starts with whsec_) is shown only in this answer — store it. An empty events list means every event. GET /api/v1/webhooks lists your webhooks with each one's last_status and last_fired_at; PUT /api/v1/webhooks/:id changes url, events or enabled; DELETE /api/v1/webhooks/:id removes one.

Each event is a POST with a JSON body and the headers X-Relaybell-Event (the event name) and X-Relaybell-Signature:

{
  "event": "notification.clicked",
  "data": { "notificationId": "5b0c2f7e-1d7a-4c3e-9a51-2f8e6b1d0c42", "variant": null },
  "projectId": "YOUR_PROJECT_ID",
  "at": "2026-10-14T09:31:12.345Z"
}

relaybell sends each event once and waits up to 10 seconds for an answer; it doesn't retry. Answer quickly with any 2xx status and do slow work afterwards.

Verify a webhook signature

X-Relaybell-Signature is sha256= followed by the lowercase hex HMAC-SHA256 of the raw request body, keyed with your webhook secret. Check it before trusting the request — against the exact bytes you received, not JSON you parsed and re-encoded — and with a constant-time comparison. A missing or malformed header must simply fail the check:

// Node.js (Express)
const crypto = require("crypto");

function verifyRelaybell(rawBody, signature, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof signature !== "string") return false;
  const expected = Buffer.from("sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"));
  const given = Buffer.from(signature);
  // timingSafeEqual throws if the lengths differ, so compare the lengths first.
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

// express.raw keeps the exact bytes relaybell signed.
app.post("/webhooks/relaybell", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyRelaybell(req.body, req.get("X-Relaybell-Signature"), process.env.RELAYBELL_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }
  const { event, data } = JSON.parse(req.body);
  res.sendStatus(200);
  // …then handle event / data
});

# Python (Flask)
import hashlib, hmac, os
from flask import Flask, abort, request

app = Flask(__name__)

def verify_relaybell(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    # compare_digest is constant-time and returns False (no error) when the lengths differ.
    return hmac.compare_digest(expected.encode(), (signature or "").encode())

@app.post("/webhooks/relaybell")
def relaybell_webhook():
    signature = request.headers.get("X-Relaybell-Signature", "")
    if not verify_relaybell(request.get_data(), signature, os.environ["RELAYBELL_WEBHOOK_SECRET"]):
        abort(401)
    payload = request.get_json()  # {"event": ..., "data": {...}, "projectId": ..., "at": ...}
    return "", 200

<?php // PHP
$raw      = file_get_contents('php://input');          // the exact bytes relaybell signed
$given    = $_SERVER['HTTP_X_RELAYBELL_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('RELAYBELL_WEBHOOK_SECRET'));
if (!hash_equals($expected, $given)) {                  // constant-time; false for any mismatch
    http_response_code(401);
    exit;
}
$payload = json_decode($raw, true);                     // ['event' => ..., 'data' => [...]]
http_response_code(200);

More

• RSS → push (/api/v1/feeds) and recurring campaigns (/api/v1/schedules).
• Copy suggestions — POST /api/v1/ai/suggest with { title, body } returns { ai, suggestions: [{ title, body }, …] }: three quick rewordings of your draft, made from simple templates (ai is false), for you to edit. 30 requests an hour.

Errors & rate limits

Errors return a JSON body { "error": "code" } (often with a readable message) and a standard HTTP status:

Rate limits

Going over a request limit answers 429 rate_limited; going over one of the three hourly send budgets (per website) answers 429 send_limit_reached. A limited route's responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). Every 429 also carries Retry-After (seconds): wait that long before trying again, rather than retrying in a loop. The hourly send budgets restart at the top of each hour; a send_limit_reached answer says which budget ran out: { "error": "send_limit_reached", "message": "…", "limit": 30, "kind": "broadcast", "retryAfter": 1260 } (kind is broadcast, transactional or test). A send refused this way isn't counted.

Sending rules: quiet hours and a per-subscriber daily frequency cap are set per website (Settings → Sending) and apply automatically — no per-request flags needed. Quiet hours hold a send that would go out now until the quiet time ends; the cap skips subscribers who already got that many notifications in the last 24 hours. Sends with transactional: true skip both.

Compliance / GDPR

relaybell records consent (time, page, policy version) on opt-in. For data-subject requests:

• GET /api/v1/subscribers/:externalId/data — export everything held about a subscriber (right to access).
• DELETE /api/v1/subscribers/:externalId — erase all of it (right to erasure).
• Set a retention window (Settings → Privacy) to auto-prune old event logs. See our Privacy Policy and DPA.

Account & support

The dashboard uses these while you're signed in (session cookie); an API key can't reach them. They're listed so you know what exists.

WordPress & WooCommerce

Install the relaybell WordPress plugin and click Connect to relaybell on its settings page — one click links the site (no keys to copy; manual Project ID + API key entry is still under Advanced). It injects the SDK, serves its own service worker, and can auto-send a push when you publish (tick Send on publish on its settings page — it's off by default). With WooCommerce active (plugin 1.2.2 or newer — older versions sent no WooCommerce events because of a loading bug), it also fires purchase, cart.updated (logged-in shoppers), signup, checkout.started, order.refunded, back_in_stock and price_drop events automatically, adds a “Notify me when back in stock” button to sold-out products (on variable products it signs the shopper up for the size/colour they picked), and records product views for subscribers so price-drop alerts reach the right people.

Identity verification: plugin 1.2.4 or newer fetches your secret key, signs the user id of each logged-in visitor (userHash) and turns on Require verified User IDs for you. It picks up a new key within a day, or as soon as you open its settings page.

Shopify

Two parts: (1) the storefront code from the dashboard's Install page (choose Shopify), added to your theme, collects subscribers; (2) Shopify webhooks pointed at https://relaybell.com/api/v1/integrations/shopify/<PROJECT_ID> send orders and carts to your automations.

Shopify topics are mapped automatically:

Required: paste your Shopify signing secret into Settings → Privacy. relaybell only accepts Shopify updates signed with it; without it, they are acknowledged but ignored, so nobody else can send fake orders or carts.

Signed-in shoppers: the storefront code links a signed-in customer by their email (externalId). Sign it too, so nobody can claim a customer's email to get their notifications — the code on the dashboard's Install → Shopify page already has this, with your key filled in. Then turn on Require verified User IDs.

{% if customer and customer.email != blank %}
externalId: {{ customer.email | json }},
userHash: "{{ customer.email | hmac_sha256: 'YOUR_SECRET_KEY' }}",
{% endif %}

Using the snippet.liquid file instead? Make sure it sets config.userHash = "{{ customer.email | hmac_sha256: 'YOUR_SECRET_KEY' }}"; right after its config.externalId line before you turn on Require — otherwise signed-in shoppers are no longer linked to their orders and carts.

Google Tag Manager

Add a Custom HTML tag in GTM, set to fire on All Pages:

<script src="https://relaybell.com/relaybell-sdk.js"></script>
<script>
  window.addEventListener('load', function () {
    RelayBell.init({ projectId: "YOUR_PROJECT_ID", apiBase: "https://relaybell.com" });
  });
</script>

Server SDKs

Thin wrappers over the REST API for your server — install from your package manager. They use your secret API key, so never put them (or the key) in code that runs in the browser; on web pages, use the relaybell-sdk.js script tag from the Quickstart.

Prefer no package manager? Zipped builds are also available: Node · PHP · Python.

// Node
const { RelayBell } = require("relaybell");
const rb = new RelayBell({ apiKey: "rb_live_xxxxx" });
await rb.send({ title: "Hello", body: "World", url: "https://example.com" });
await rb.track("purchase", { externalId: "user_123", properties: { value: 42 } });

# PHP
$rb = new Relaybell\Client("rb_live_xxxxx");
$rb->send(["title" => "Hello", "body" => "World", "url" => "https://example.com"]);

# Python
from relaybell import RelayBell
rb = RelayBell("rb_live_xxxxx")
rb.send(title="Hello", body="World", url="https://example.com")

Each SDK can also make the userHash for identity verification, with no network call: Node userHash(secret, externalId), PHP Relaybell\Client::userHash($secret, $externalId), Python user_hash(secret, external_id) (Python SDK 1.1.0 or newer).

Zapier

Connect relaybell to thousands of apps with no code. Actions: Send Notification and Track Event; trigger: New Subscriber. You connect it with an API key from Settings → Developer → API keys. note relaybell isn't in Zapier's public app directory yet (Zapier is still reviewing it), so searching for it in Zapier won't find it — contact us for an invite link.

Browser support

Standards-based Web Push (VAPID) works on Chrome, Firefox, Edge, Opera, Samsung Internet, and Brave (desktop & Android), and Safari 16.1+ on macOS 13 (Ventura) and later, plus Safari on iOS/iPadOS 16.4+ (iPhone/iPad requires adding the site to the Home Screen, which the SDK guides). Dead subscriptions are pruned automatically.