Use SignalOps webhooks to push commerce events into your backend.

Why merchant teams use webhooks

The Commerce Ingestion API gets order data into SignalOps. Webhooks tell the merchant system what happened after the data arrived. That matters when the merchant has its own admin, ERP, Slack automation, support queue, warehouse workflow, or business intelligence layer that needs to react to SignalOps output.

A webhook keeps the merchant backend in control. SignalOps delivers a signed POST request, the merchant verifies it, stores the event, and chooses what should happen next.

Event flow

1. A merchant backend sends orders to POST /api/v1/ingest/orders with a server-side API key.
2. SignalOps validates the payload and stores the import run.
3. If run_analysis is enabled, SignalOps runs revenue leak analysis and prepares recovery recommendations.
4. For each subscribed event, SignalOps posts a JSON payload to the merchant webhook URL.
5. The merchant backend verifies the signature, stores the event, and returns a 2xx response.

Webhook events

Create a webhook endpoint

The endpoint should respond quickly. Do slow work in a background job after you verify and store the event. SignalOps records the latest delivery status, status code, and delivery time in the Developer console.

Payload and headers

SignalOps sends compact JSON with the event name, creation time, and import or analysis identifiers.

POST /signalops/webhook
Content-Type: application/json
User-Agent: SignalOps-Webhooks/1.0
X-SignalOps-Event: analysis.completed
X-SignalOps-Timestamp: 1789794000
X-SignalOps-Signature: sha256=8f2f...

{
  "event": "analysis.completed",
  "created_at": "2026-09-19T10:20:00Z",
  "data": {
    "import_id": 42,
    "source": "Acme backend",
    "source_type": "api",
    "order_count": 1842,
    "linked_analysis_run_id": 77,
    "run_id": 77
  }
}

Verify the signature

Always verify against the raw request body before parsing or transforming JSON. Build the signed message as:

{timestamp}.{raw_body}

Then compute HMAC SHA-256 using the webhook signing secret copied from SignalOps.

expected = "sha256=" + hmac_sha256(signing_secret, timestamp + "." + raw_body)

Compare signatures with a constant-time comparison. Also reject requests with missing headers, invalid timestamps, or timestamps outside your replay window.

Example: Node and Express receiver

import crypto from "node:crypto";
import express from "express";

const app = express();
const signingSecret = process.env.SIGNALOPS_WEBHOOK_SECRET;

app.post(
  "/signalops/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const timestamp = req.header("X-SignalOps-Timestamp");
    const signature = req.header("X-SignalOps-Signature") || "";

    if (!timestamp || !signingSecret) {
      return res.sendStatus(401);
    }

    const ageSeconds = Math.abs(Date.now() / 1000 - Number(timestamp));
    if (!Number.isFinite(ageSeconds) || ageSeconds > 300) {
      return res.sendStatus(401);
    }

    const body = req.body;
    const expected =
      "sha256=" +
      crypto
        .createHmac("sha256", signingSecret)
        .update(Buffer.concat([Buffer.from(`${timestamp}.`), body]))
        .digest("hex");

    const expectedBuffer = Buffer.from(expected);
    const receivedBuffer = Buffer.from(signature);
    if (
      expectedBuffer.length !== receivedBuffer.length ||
      !crypto.timingSafeEqual(expectedBuffer, receivedBuffer)
    ) {
      return res.sendStatus(401);
    }

    const event = JSON.parse(body.toString("utf8"));

    // Store first, then handle in a job queue.
    // Use event.event + event.data.import_id + event.data.run_id for dedupe.
    console.log("SignalOps event", event.event, event.data);

    return res.sendStatus(204);
  }
);

app.listen(3000);

Example: Python and FastAPI receiver

import hashlib
import hmac
import os
import time

from fastapi import FastAPI, Header, HTTPException, Request

app = FastAPI()
SIGNING_SECRET = os.environ["SIGNALOPS_WEBHOOK_SECRET"]


@app.post("/signalops/webhook")
async def signalops_webhook(
    request: Request,
    x_signalops_timestamp: str | None = Header(default=None),
    x_signalops_signature: str | None = Header(default=None),
):
    if not x_signalops_timestamp or not x_signalops_signature:
        raise HTTPException(status_code=401, detail="Missing webhook signature")

    try:
        timestamp = int(x_signalops_timestamp)
    except ValueError as exc:
        raise HTTPException(status_code=401, detail="Invalid timestamp") from exc

    if abs(int(time.time()) - timestamp) > 300:
        raise HTTPException(status_code=401, detail="Stale webhook")

    raw_body = await request.body()
    signed_message = f"{x_signalops_timestamp}.".encode("utf-8") + raw_body
    expected = "sha256=" + hmac.new(
        SIGNING_SECRET.encode("utf-8"),
        signed_message,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, x_signalops_signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = await request.json()
    # Store event, dedupe it, then enqueue internal work.
    return {"ok": True}

What to do after receiving events

Reliability checklist

• Return 2xx only after the signature is valid and the event is stored.
• Respond quickly and move slow work to a queue.
• Dedupe events by event, data.import_id, data.run_id, and created_at.
• Reject stale timestamps, such as requests older than five minutes.
• Keep the signing secret in a secret manager or encrypted environment variable.
• Rotate the webhook by creating a new endpoint, deploying the new secret, then revoking the old endpoint.
• Watch the Developer console delivery status after deploys and endpoint changes.

Related engineering guides

Read the Commerce Ingestion API guide

Read the MCP agent tools architecture guide