Webhooks

• Endpoints belong to an environment. Production and Staging each have their own list; an endpoint only ever receives that environment’s traffic.
• You subscribe by topic. event.tracked.flow_completed, user.updated, content.published, … — or a whole family at once so future additions flow in automatically.
• Every message is signed with a per-endpoint secret (X-Usertour-Signature), so your receiver can verify it really came from Usertour and hasn’t been tampered with.
• Delivery is at-least-once with retries. A stable message id lets you deduplicate; the message log shows every attempt and lets you re-send.
• Availability. On Usertour Cloud, webhooks are included from the Starter plan; self-hosted instances are never gated. Managing endpoints requires the Owner role.

​

Create an endpoint

​

Topics

​

Message format

{
  "id": "whmsg_fedf230a05d01bfe38e494fb65b24e8a",
  "object": "webhookMessage",
  "type": "event.tracked.flow_completed",
  "createdAt": "2026-08-18T06:22:57.445Z",
  "environmentId": "cmsifx2vh00yombd93flnwito",
  "data": { ... }
}

​

event.tracked.*

{
  "data": {
    "event": {
      "id": "cmsy9dq2v000589thb2k9v6zj",
      "object": "event",
      "codeName": "flow_completed",
      "eventDefinitionId": "cmso7q1e800xdli95v3s6i2m9",
      "createdAt": "2026-08-18T06:25:21.100Z",
      "userId": "user_123",
      "companyId": "acme",
      "sessionId": "cmsy9dpz9000389th7v6c1w9k",
      "contentId": "cmso7pqf000x8li95p8sa0ca1",
      "versionId": "cmso7pqf500xali95hneffgbl",
      "attributes": {
        "flow_id": "cmso7pqf000x8li95p8sa0ca1",
        "flow_name": "Onboarding",
        "flow_version_id": "cmso7pqf500xali95hneffgbl",
        "flow_version_number": 1,
        "page_url": "https://app.example.com/dashboard",
        "viewport_width": 1440,
        "viewport_height": 852
      }
    }
  }
}

​

content.published

{ "data": { "contentId": "cmso7pqf000x8li95p8sa0ca1", "versionId": "cmso7pqf500xali95hneffgbl" } }

​

user.created / user.updated / user.deleted and company.*

{
  "data": {
    "user": {
      "id": "user_123",
      "object": "user",
      "attributes": { "name": "Ada Lovelace", "plan": "growth", "email": "ada@example.com" },
      "createdAt": "2026-07-01T09:00:00.000Z",
      "companies": null,
      "memberships": null
    },
    "previousAttributes": { "plan": "starter" }
  }
}

​

webhook.test

​

Verify the signature

X-Usertour-Signature: t=1787034177,v1=1f72734d33a5d2433ad825e7891c37ac3bf6910010f946098c8d9c53169bae42

• t — Unix timestamp (seconds) of the attempt
• v1 — HMAC-SHA256, hex, keyed with the endpoint’s signing secret (the whole whsec_… string), over the string "{t}.{raw body}"

const express = require('express');
const { createHmac, timingSafeEqual } = require('node:crypto');

const SECRET = process.env.USERTOUR_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SEC = 300;

const app = express();

// Raw body: the signature is over the exact bytes Usertour sent.
app.post('/usertour', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Usertour-Signature') ?? '';
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
  const t = Number(parts.t);
  const v1 = parts.v1 ?? '';

  if (!t || Math.abs(Date.now() / 1000 - t) > TOLERANCE_SEC) {
    return res.status(400).send('stale');
  }

  const expected = createHmac('sha256', SECRET)
    .update(`${t}.${req.body.toString('utf8')}`)
    .digest('hex');
  if (expected.length !== v1.length || !timingSafeEqual(Buffer.from(expected), Buffer.from(v1))) {
    return res.status(401).send('bad signature');
  }

  const message = JSON.parse(req.body.toString('utf8'));
  // Deduplicate on message.id, respond 2xx quickly, then process.
  res.status(200).send('ok');
  handle(message);
});

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

SECRET = os.environ["USERTOUR_WEBHOOK_SECRET"].encode()  # whsec_…
TOLERANCE_SEC = 300

app = Flask(__name__)

@app.post("/usertour")
def usertour():
    header = request.headers.get("X-Usertour-Signature", "")
    parts = dict(kv.split("=", 1) for kv in header.split(",") if "=" in kv)
    t = int(parts.get("t", "0") or 0)
    v1 = parts.get("v1", "")

    if not t or abs(time.time() - t) > TOLERANCE_SEC:
        abort(400)

    body = request.get_data()  # raw bytes
    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, v1):
        abort(401)

    message = request.get_json()
    # Deduplicate on message["id"], respond 2xx quickly, then process.
    return "ok", 200

​

Delivery, retries, and the message log

• Success is any 2xx response within 10 seconds. Respond first, do the work afterwards.
• Anything else — a non-2xx status, a timeout, a connection error, or a redirect — counts as a failure and is retried with growing delays over roughly 24 hours: 8 attempts in total (after ~5 s, 1 m, 10 m, 1 h, 4 h, 8 h, 12 h). An outage on your side that lasts less than a day heals itself — every message is delivered once the receiver is back, no action needed. All attempts carry the same body and message id; only the signature timestamp changes.
• Rate limiting: respond 429 (or 503) with a Retry-After header and the next attempt waits at least that long (never sooner than the schedule above); the header is ignored on other statuses.
• Ordering is not guaranteed across messages; use createdAt (and the object’s own timestamps) rather than arrival order.
• Repeated failures pause deliveries briefly. After 10 failed attempts in a row the endpoint cools down (starting at 1 minute, growing to at most 1 hour while failures continue — the dashboard shows a Cooling down badge). Deliveries are held, not dropped: everything is sent once the pause ends or a Send test event succeeds. If an endpoint keeps failing for 7 days, Usertour disables it and emails the project owner; re-enable it after fixing the receiver and use Resend for anything you need.
• Disabled or deleted endpoints drop their in-flight deliveries; the drops are recorded in the message log as failed attempts, so after re-enabling you can see and re-send what was missed.
• The message log on the endpoint’s detail page keeps every message for 30 days: the payload as sent and each attempt with status code, response excerpt, and error. Open a message to inspect it or Resend it — the same payload under the same message id, as one more attempt — after fixing your receiver.

​

Manage endpoints from the API or MCP