Integrations

Integrations connects RateUp to everything outside it — your own systems, and the platforms you already run your business on. The entry appears under Settings when your team has the integrations feature.

Find Your Way AroundCopy Anchor Link

Connecting usually sends you to the other platform to authorise RateUp, then brings you back to the service's page here.

WebhookCopy Anchor Link

The Webhook integration sends events to one HTTPS endpoint for the whole organisation, as they happen: WhatsApp message statuses, new inbound messages, contact and lead changes, survey responses and loyalty points. Every delivery is signed and retried.

Set it upCopy Anchor Link

GET https://example.com/webhook?challenge=<your-verify-token>

app.get("/webhook", (req, res) => {
  res.type("text/plain").send(req.query.challenge);
});

Choose the EventsCopy Anchor Link

The Events card lists every event in seven groups — Messages, Contacts, Conversations, Leads, Surveys & Flows, Team and Loyalty — each with its name and code (contact.created). Use Search events to filter, the group's checkbox to tick or clear a whole group, and Select all / Clear for everything. The card's description counts what you send: "4 of 19 events are sent to your endpoint."

Ticks are not saved one by one. Once you change something, a bar at the bottom of the card shows Discard and Save events; nothing reaches your endpoint differently until you save. Events marked Envelope arrive in the envelope shape described under Payloads.

The loyalty events cover purchases, signup and referral bonuses, redemptions, approved adjustments and purchase reversals. Points expiry and a programme reset are not announced.

PayloadsCopy Anchor Link

Events come in two shapes.

Envelope events — message.status, survey.response.created, flow.response.created and the three loyalty.points.* events:

{
  "id": "6f1d2c3b-…",
  "type": "message.status",
  "createdAt": "2026-10-16T09:32:03.000Z",
  "orgId": "a1b2…",
  "data": {
    "messageId": "wamid.HBgMOTE5…",
    "status": "failed",
    "timestamp": "2026-10-16T09:32:03.000Z",
    "recipientPhone": "919876543210",
    "channel": "15550100142",
    "templateName": "order_shipped",
    "source": "template",
    "campaignId": null,
    "error": { "code": 131026, "title": "Message undeliverable", "message": "…" }
  }
}

id is unique per event — use it to drop a repeat. message.status announces each status once, and only statuses Meta actually reported. source says what sent the message (campaign, inbox, template, automated, …) and is null on older messages.

A loyalty event's data:

{
  "transactionId": "tx_5e6f…",
  "member": { "phone": "919876543210", "cardCode": "ABCDEFGHJ" },
  "points": 125,
  "balanceAfter": 845,
  "type": "earn",
  "source": "purchase",
  "reason": null,
  "referenceId": "1042",
  "idempotencyKey": "pos-store7-order-1042",
  "createdAt": "2026-10-16T09:30:00.000Z"
}

survey.response.created carries { survey: { id, title, type }, platform, response }, where survey.type is web, whatsapp or waFlow, and response has the same fields as the External API's survey responses — including empty answers and the ciphertext in encryptedAnswers when your responses are encrypted.

flow.response.created carries the same fields plus the flow that collected the answers:

{
  "flow": {
    "id": "6f1c2b9e-0000-4000-8000-0000000000a1",
    "metaFlowId": "1234567890123456",
    "name": "Visit feedback",
    "categories": ["SURVEY"]
  },
  "survey": { "id": "…", "title": "Visit feedback", "type": "waFlow" },
  "platform": "WHATSAPP",
  "response": { "id": "…", "phone": "919876543210", "answers": [ … ] }
}

flow.id is RateUp's id for the flow; metaFlowId is the id Meta knows it by, and is null until the flow has been saved to WhatsApp.

Flat events — every other event — are { "event": "<name>", …fields }. The original Message Status event looks like this:

{
  "event": "message_status",
  "status": "delivered",
  "messageId": "wamid.HBgMOTE5...",
  "recipientId": "14155552671",
  "timestamp": "1726567200",
  "errors": null
}

The contact events carry contact: { id, name, phone, email, source, lifecycleId }.

Verify the signatureCopy Anchor Link

There is one webhook per organisation, receiving every event you tick, and it is configured here in the dashboard — it is not tied to an API key. Every delivery is signed with the organisation's signing secret (whsec_…, from the Signing secret card) and carries these headers:

To check X-Rateup-Signature-256:

1. Read the raw request body — the exact bytes received, before any JSON parsing.
2. Split the header on , and take t and v1.
3. Reject the request if t is more than 5 minutes from your clock. This stops a captured delivery from being replayed later.
4. Compute HMAC-SHA256 over the string <t>.<raw body> (the timestamp, a full stop, then the body), keyed with the whole secret string exactly as shown, whsec_ prefix included, as UTF-8. Hex-encode it (lowercase).
5. Compare it with v1 in constant time. Accept only on a match.
6. Drop the delivery if you have already processed its X-Webhook-Id.

Node.js (Express):

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.RATEUP_WEBHOOK_SECRET; // "whsec_…", used as-is
const TOLERANCE_SECONDS = 300;

function verifyRateupSignature(secret, header, rawBody, now = Math.floor(Date.now() / 1000)) {
  if (!header) return false;
  let timestamp;
  const signatures = [];
  for (const part of header.split(",")) {
    const [key, value] = part.trim().split("=", 2);
    if (key === "t" && /^\d+$/.test(value ?? "")) timestamp = Number(value);
    if (key === "v1" && /^[0-9a-f]{64}$/i.test(value ?? "")) signatures.push(value.toLowerCase());
  }
  if (timestamp === undefined || signatures.length === 0) return false;
  if (Math.abs(now - timestamp) > TOLERANCE_SECONDS) return false;

  const expected = Buffer.from(
    createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex"),
  );
  return signatures.some((signature) => {
    const given = Buffer.from(signature);
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

const app = express();

// express.raw keeps req.body as the bytes received; express.json would break the check.
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyRateupSignature(SECRET, req.get("X-Rateup-Signature-256"), req.body)) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // acknowledge first, then work
  const deliveryId = req.get("X-Webhook-Id"); // skip it if already processed
  queue.push({ deliveryId, event: JSON.parse(req.body) });
});

Python (Flask):

import hashlib, hmac, os, time
from flask import Flask, request, abort

SECRET = os.environ["RATEUP_WEBHOOK_SECRET"]  # "whsec_…", used as-is
TOLERANCE_SECONDS = 300

def verify_rateup_signature(secret: str, header: str | None, raw_body: bytes) -> bool:
    if not header:
        return False
    timestamp, signatures = None, []
    for part in header.split(","):
        key, _, value = part.strip().partition("=")
        if key == "t" and value.isdigit():
            timestamp = int(value)
        elif key == "v1":
            signatures.append(value.lower())
    if timestamp is None or not signatures:
        return False
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in signatures)

app = Flask(__name__)

@app.post("/webhook")
def webhook():
    if not verify_rateup_signature(
        SECRET, request.headers.get("X-Rateup-Signature-256"), request.get_data()
    ):
        abort(401)
    # De-duplicate on request.headers["X-Webhook-Id"], then process request.get_json()
    return "", 200

To test your code, this fixed input must produce this signature:

So the header is t=1760611200,v1=024c8192…c98aa6b (the full 64 hex characters).

The legacy X-Rateup-Signature header is still sent on every delivery so existing receivers keep working: the base64 HMAC-SHA256 of the raw body, keyed with the same secret. It does not cover a timestamp, so a captured delivery verifies forever. It is deprecated — move to X-Rateup-Signature-256.

Replace secret issues a new signing secret. Deliveries are signed with it straight away, so your endpoint rejects them until it is updated — have the new value ready to deploy first.

RetriesCopy Anchor Link

A delivery that does not get a 2xx within 15 seconds — including any 4xx, 5xx, timeout or redirect — is retried, up to five attempts in all with exponential backoff starting at about 5 seconds. After the fifth failure it is dropped. A URL that resolves to a private address is not retried.

Acknowledge with a 2xx immediately and process the payload afterwards. Deliveries are independent: they can arrive out of order, and a retry can arrive after a later event.

Change the URLCopy Anchor Link

On the Endpoint card, click Change, edit the URL and enter the Verify token again — saving re-runs the URL check, and RateUp does not keep a token it could show back. Cancel keeps the current endpoint. The events and the signing secret stay as they are.

Remove itCopy Anchor Link

Remove on the Endpoint card asks "Remove the webhook?"; Remove webhook stops all deliveries straight away and deletes the signing secret. Setting the webhook up again issues a new secret.

TroubleshootingCopy Anchor Link

API ServiceCopy Anchor Link

API Service is where you create and manage the keys your own systems use to call the External API. It opens from RateUp services → API Service; seeing it needs the API keys abilities, which Owners and Admins have by default — see Members & Roles.

Create a keyCopy Anchor Link

An organisation can hold 20 keys. At the limit Create key is disabled — "Revoke one to create another."

The keys tableCopy Anchor Link

The ⋯ menu on each row:

UsageCopy Anchor Link

The Usage card charts requests made with your keys over the last 14 days, stacked as Successful, Client errors (4xx) and Server errors (5xx). With more than one key, filter by key. Recent requests lists each call — Method, Route, Status, Latency, Key and Time — 25 to a page, newest first. Calls appear within a few seconds; the log keeps 30 days.

A rising Client errors line after a rotation or a change of access is usually an integration still sending an old key or calling outside its features.

Base URLCopy Anchor Link

The Base URL card shows both endpoints, with copy buttons:

API documentation opens the docs. The same keys card also sits on Loyalty → Settings as POS and API access, for a till that awards points directly.

WidgetCopy Anchor Link

Widget is a chat button for your own website, shipped as the @rateup/support-widget React package. Visitors chat from it, and their messages land in your Inbox as Webchat tickets. It opens from RateUp services → Widget. On Shopify you don't need it — "Add a WhatsApp button to your store without code" from the Shopify integration instead. On WooCommerce, use the integration's WhatsApp widget tab (see WooCommerce).

The widget refuses a key limited to other features (say, only Contacts): its chat does not connect and its requests answer 403. It also takes only keys that start with rk_, since those name their organization; an older key answers 401.

WooCommerceCopy Anchor Link

The WooCommerce integration connects one WordPress store. RateUp hears about new orders, order status changes, new customers and product changes, which drive order automations, loyalty points and coupons. Connecting a store also turns Commerce on in Features.

Two parts work together:

Connect your storeCopy Anchor Link

If you arrive from the plugin's own Connect to RateUp button in WordPress, the store address is filled in for you — you still click Connect.

Install the RateUp pluginCopy Anchor Link

The plugin is listed on WordPress.org as RateUp for WooCommerce. Wherever RateUp needs it, it shows Install the RateUp plugin with the steps:

The Connection tabCopy Anchor Link

The checkout box is unticked by default and is marketing consent only — order updates are sent either way:

The Connection card's description names the key RateUp holds — "To revoke RateUp's access from the store side, delete key #… under WooCommerce › Settings › Advanced › REST API."

WooCommerce troubleshootingCopy Anchor Link

Before You ConnectCopy Anchor Link

• Check which direction data flows — some integrations write into RateUp, some read out of it
• Check what it syncs — contacts, orders, leads, or several
• Connect with an account that will still exist in six months, not a personal one

Related PagesCopy Anchor Link

• External API — endpoints, errors, retries and the v1 → v2 migration
• Members & Roles — who may manage API keys and webhooks
• Web Forms → Settings — a form's own response webhook
• Message Analytics — the same delivery data, in the dashboard
• Channels