Webhooks

Optional fields can be missing on older data; treat missing as unknown.

messaging

Homepage headline and/or primary call to action. Each key is present only if that element changed.

"type": "messaging",
"payload": {
  "headline": { "before": "Analytics for growing teams", "after": "The analytics platform for enterprises" },
  "cta": { "before": "Start free", "after": "Book a demo" }
}

pages

New URLs discovered in the competitor’s sitemap.

"type": "pages",
"payload": {
  "pages": [
    "https://rival.example/features/sso",
    "https://rival.example/solutions/enterprise"
  ]
}

changelog

New entries on the competitor’s changelog or release-notes page: the page URL and the new entry headings, in page order (usually newest first).

"type": "changelog",
"payload": {
  "url": "https://rival.example/changelog",
  "entries": [
    "SAML single sign-on is now available",
    "New usage-based billing for API calls"
  ]
}

Payload: report.test

Sent by Send test. It is signed like a real delivery but contains fixed sample data in a simplified shape — don’t use it to build your parser. There is no report_url or generated_at; the send time is in delivered_at.

{
  "event": "report.test",
  "delivered_at": "2026-10-08T14:21:09.338Z",
  "report": {
    "title": "Weekly Intelligence Brief — sample",
    "period": "Mar 1 – Mar 7, 2026",
    "competitor": "Acme Analytics",
    "changes": [
      { "type": "pricing", "title": "Pricing page updated", "priority": "high" },
      { "type": "messaging", "title": "Homepage headline changed", "priority": "medium" },
      { "type": "pages", "title": "3 new pages discovered", "priority": "medium" }
    ]
  }
}

Verifying signatures

The header has the form t=<unix seconds>,v1=<hex>. v1 is the hex-encoded HMAC-SHA256 of the string `${t}.${body}` — the timestamp, a literal dot, then the exact raw request body — keyed with your channel’s secret. The key is the whole secret string as shown in Settings, including the whsec_ prefix.

signed_payload = "{t}.{raw_request_body}"
expected       = hex( HMAC_SHA256( key = "whsec_…", message = signed_payload ) )
valid          = constant_time_equal(expected, v1) and |now - t| <= 300

1. Read the raw body before parsing JSON. Re-serialising parsed JSON changes the bytes and the signature won’t match.
2. Compare with a constant-time function, not ==.
3. Reject timestamps more than 5 minutes from your clock to block replayed requests.
4. Respond 400 on failure. Rotate the secret in Settings if it may have leaked; the old one stops working immediately.

Node.js

import crypto from 'node:crypto';
import express from 'express';

// The full secret from Settings, including the "whsec_" prefix.
const SECRET = process.env.COMPETITORMOVE_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 5 * 60;

export function verifyCompetitorMoveSignature(rawBody, header, secret, toleranceSeconds = TOLERANCE_SECONDS) {
  if (!header || !secret) return false;

  const parts = {};
  for (const piece of header.split(',')) {
    const i = piece.indexOf('=');
    if (i > 0) parts[piece.slice(0, i).trim()] = piece.slice(i + 1).trim();
  }
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!Number.isInteger(t) || !v1) return false;

  // Reject stale (or future) timestamps to block replays.
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - t) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(v1, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

// Use the raw body: re-serialising parsed JSON changes bytes and breaks the HMAC.
app.post('/webhooks/competitor-move', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const header = req.get('X-CompetitorMove-Signature');

  if (!verifyCompetitorMoveSignature(rawBody, header, SECRET)) {
    return res.status(400).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);
  res.sendStatus(204); // acknowledge quickly; do heavy work asynchronously

  if (event.event === 'report.generated') {
    // De-duplicate on event.report.id — a report can be re-sent manually.
    for (const change of event.report.changes) {
      console.log(change.competitor.display_name, change.type, change.title);
    }
  }
});

app.listen(3000);

Python

import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

# The full secret from Settings, including the "whsec_" prefix.
SECRET = os.environ["COMPETITORMOVE_WEBHOOK_SECRET"]
TOLERANCE_SECONDS = 5 * 60


def verify_competitor_move_signature(raw_body: bytes, header: str | None, secret: str,
                                     tolerance: int = TOLERANCE_SECONDS) -> bool:
    if not header or not secret:
        return False

    parts = {}
    for piece in header.split(","):
        key, sep, value = piece.partition("=")
        if sep:
            parts[key.strip()] = value.strip()

    try:
        t = int(parts["t"])
        v1 = parts["v1"]
    except (KeyError, ValueError):
        return False

    # Reject stale (or future) timestamps to block replays.
    if abs(int(time.time()) - t) > tolerance:
        return False

    signed_payload = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)


app = Flask(__name__)


@app.post("/webhooks/competitor-move")
def competitor_move_webhook():
    raw_body = request.get_data()  # raw bytes, before any JSON parsing
    header = request.headers.get("X-CompetitorMove-Signature")

    if not verify_competitor_move_signature(raw_body, header, SECRET):
        abort(400)

    event = json.loads(raw_body)
    if event["event"] == "report.generated":
        # De-duplicate on event["report"]["id"] — a report can be re-sent manually.
        for change in event["report"]["changes"]:
            print(change["competitor"]["display_name"], change["type"], change["title"])

    return "", 204

Delivery and retries

• When: reports are generated weekly (Mondays, around 06:00 UTC) when there were changes in the period, or on demand with Generate now on the Reports page. Deliveries go out in a daily run around 07:00 UTC. Scheduled times are approximate.
• Success means your endpoint returned a 2xx status within 10 seconds. Your response body is ignored.
• Once per channel: each report is delivered successfully at most once per channel by the scheduled run. If a delivery fails, it is retried on later daily runs for up to 72 hours after the report was generated, then dropped. Delivery status per channel is shown on the report page.
• Manual re-sends: a report re-sent manually is deliberately delivered again, so de-duplicate on report.id.
• HTTPS only. The URL must be https:// on the default port and resolve to a public IP address.
• Redirects are not followed. A 3xx response counts as a failure — configure the final URL.
• Any other non-2xx status, a timeout or a connection error is a failure.

Questions

Email hello@competitormove.com. Security issues: security@competitormove.com — see our Security page.