Webhooks

Webhooks let you receive HTTP POST notifications when events occur in your Shelfforce account. Instead of polling for analysis results, register a webhook URL and Shelfforce will notify you as soon as results are ready.

Available events

Event	Description
`analysis.completed`	An image analysis finished successfully and products are available.
`analysis.failed`	An image analysis encountered an error and could not produce results.
`task.created`	A new task was created.
`task.updated`	A task’s status or details were modified.
`task.completed`	A task moved to the `completed` status.
`*`	Wildcard — receive all events.

Registering a webhook

Create a webhook by sending a POST request with an admin-role API key:

curl -X POST https://shelfforce.ai/api/v1/webhooks \
  -H "Authorization: Bearer sf_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/shelfforce",
    "events": ["analysis.completed", "analysis.failed"],
    "description": "Production analysis handler"
  }'

import requests

response = requests.post(
    "https://shelfforce.ai/api/v1/webhooks",
    headers={
        "Authorization": "Bearer sf_live_a1b2c3d4...",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://your-app.com/webhooks/shelfforce",
        "events": ["analysis.completed", "analysis.failed"],
        "description": "Production analysis handler",
    },
)

webhook = response.json()["data"]
print(webhook["secret"])  # Store this securely!

const response = await fetch("https://shelfforce.ai/api/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sf_live_a1b2c3d4...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-app.com/webhooks/shelfforce",
    events: ["analysis.completed", "analysis.failed"],
    description: "Production analysis handler",
  }),
});

const { data: webhook } = await response.json();
console.log(webhook.secret); // Store this securely!

Response:

{
  "data": {
    "id": "wh_abc123",
    "url": "https://your-app.com/webhooks/shelfforce",
    "events": ["analysis.completed", "analysis.failed"],
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0",
    "status": "active",
    "createdAt": "2026-02-23T10:00:00Z"
  }
}

The webhook secret is returned only once at creation. Store it securely — you will need it to verify webhook signatures.

Webhook delivery format

Every webhook delivery is an HTTP POST to your registered URL. Here is the full shape of what hits your endpoint.

HTTP headers

POST /webhooks/shelfforce HTTP/1.1
Host: your-app.com
Content-Type: application/json
User-Agent: Shelfforce-Webhooks/1.0
X-Shelfforce-Signature: t=1740312618,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
X-Shelfforce-Event: analysis.completed
X-Shelfforce-Delivery: evt_abc123

Header	Description
`X-Shelfforce-Signature`	HMAC-SHA256 signature for verification (see Signature verification)
`X-Shelfforce-Event`	The event type (e.g., `analysis.completed`)
`X-Shelfforce-Delivery`	Unique delivery ID for idempotency tracking
`Content-Type`	Always `application/json`

JSON body structure

Every webhook body follows the same top-level structure:

{
  "event": "analysis.completed",
  "data": { ... },
  "timestamp": "2026-02-23T10:32:00Z",
  "webhookId": "wh_abc123"
}

Field	Type	Description
`event`	`string`	The event type that triggered this delivery
`data`	`object`	Event-specific payload (see examples below)
`timestamp`	`string`	ISO 8601 timestamp of when the event occurred
`webhookId`	`string`	ID of the webhook endpoint that received this delivery

Payload examples by event type

analysis.completed
analysis.failed
task.created
task.updated
task.completed

Fired when a shelf analysis finishes successfully.

{
  "event": "analysis.completed",
  "data": {
    "id": "an_g7h8j9k0",
    "externalId": "customer-123",
    "metadata": { "store": "store-42", "aisle": "3" },
    "status": "completed",
    "totalRuns": 1,
    "productCount": 12,
    "totalUnits": 48,
    "totalValue": 127.50,
    "completedAt": "2026-02-23T10:32:00Z"
  },
  "timestamp": "2026-02-23T10:32:00Z",
  "webhookId": "wh_abc123"
}

The externalId and metadata fields are included when they were provided at submission time. Use the id to fetch the full analysis with products:

curl https://shelfforce.ai/api/v1/analyses/an_g7h8j9k0 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

Fired when a shelf analysis encounters an error.

{
  "event": "analysis.failed",
  "data": {
    "id": "an_g7h8j9k0",
    "externalId": "customer-123",
    "metadata": { "store": "store-42", "aisle": "3" },
    "status": "failed",
    "failedRuns": 1
  },
  "timestamp": "2026-02-23T10:31:00Z",
  "webhookId": "wh_abc123"
}

Fired when a new task is created.

{
  "event": "task.created",
  "data": {
    "taskId": "tsk_xyz789",
    "title": "Check Coca-Cola facing at Walmart #4523",
    "placeId": "pl_abc123",
    "status": "pending",
    "createdAt": "2026-02-23T10:30:00Z"
  },
  "timestamp": "2026-02-23T10:30:01Z",
  "webhookId": "wh_abc123"
}

Fired when a task’s fields are modified.

{
  "event": "task.updated",
  "data": {
    "taskId": "tsk_xyz789",
    "title": "Check Coca-Cola facing at Walmart #4523",
    "status": "in_progress",
    "updatedFields": ["status", "assignedTo"]
  },
  "timestamp": "2026-02-23T12:00:00Z",
  "webhookId": "wh_abc123"
}

Fired when a task is marked as completed. Includes the analysis and compliance score if available.

{
  "event": "task.completed",
  "data": {
    "taskId": "tsk_xyz789",
    "title": "Check Coca-Cola facing at Walmart #4523",
    "placeId": "pl_abc123",
    "generationId": "an_g7h8j9k0",
    "complianceScore": 87.5
  },
  "timestamp": "2026-02-23T14:00:00Z",
  "webhookId": "wh_abc123"
}

Webhook receiver examples

Copy-paste these handlers to get a working webhook receiver. They verify the signature and handle each event type.

import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf; } }));

const WEBHOOK_SECRET = process.env.SHELFFORCE_WEBHOOK_SECRET!;

function verifySignature(rawBody: Buffer, signatureHeader: string): boolean {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => {
      const [key, value] = part.split("=");
      return [key, value];
    })
  );

  const timestamp = parts["t"];
  const signature = parts["v1"];
  if (!timestamp || !signature) return false;

  // Reject requests older than 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > 300) return false;

  const signedPayload = `${timestamp}.${rawBody.toString()}`;
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(signedPayload)
    .digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

app.post("/webhooks/shelfforce", (req, res) => {
  const signatureHeader = req.headers["x-shelfforce-signature"] as string;
  if (!verifySignature((req as any).rawBody, signatureHeader)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  // Respond immediately — process asynchronously
  res.status(200).json({ received: true });

  const { event, data } = req.body;

  switch (event) {
    case "analysis.completed":
      console.log(`Analysis ${data.generationId} completed with ${data.productCount} products`);
      // Fetch full results: GET /api/v1/analyses/{data.generationId}
      break;

    case "analysis.failed":
      console.error(`Analysis ${data.generationId} failed: ${data.error}`);
      break;

    case "task.created":
      console.log(`Task ${data.taskId} created: ${data.title}`);
      break;

    case "task.updated":
      console.log(`Task ${data.taskId} updated: ${data.updatedFields.join(", ")}`);
      break;

    case "task.completed":
      console.log(`Task ${data.taskId} completed — compliance: ${data.complianceScore}%`);
      break;
  }
});

app.listen(3000, () => console.log("Webhook receiver running on port 3000"));

import hmac
import hashlib
import time
import os
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

WEBHOOK_SECRET = os.environ["SHELFFORCE_WEBHOOK_SECRET"]


def verify_signature(raw_body: bytes, signature_header: str) -> bool:
    parts = dict(part.split("=", 1) for part in signature_header.split(","))
    timestamp = parts.get("t")
    signature = parts.get("v1")

    if not timestamp or not signature:
        return False

    # Reject requests older than 5 minutes
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        return False

    signed_payload = f"{timestamp}.{raw_body.decode()}"
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        signed_payload.encode(),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(signature, expected)


@app.post("/webhooks/shelfforce")
async def handle_webhook(request: Request):
    raw_body = await request.body()
    signature = request.headers.get("x-shelfforce-signature", "")

    if not verify_signature(raw_body, signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    payload = await request.json()
    event = payload["event"]
    data = payload["data"]

    if event == "analysis.completed":
        print(f"Analysis {data['generationId']} completed with {data['productCount']} products")
        # Fetch full results: GET /api/v1/analyses/{data['generationId']}

    elif event == "analysis.failed":
        print(f"Analysis {data['generationId']} failed: {data['error']}")

    elif event == "task.created":
        print(f"Task {data['taskId']} created: {data['title']}")

    elif event == "task.updated":
        print(f"Task {data['taskId']} updated: {', '.join(data['updatedFields'])}")

    elif event == "task.completed":
        print(f"Task {data['taskId']} completed — compliance: {data['complianceScore']}%")

    return {"received": True}

Your webhook endpoint should return a 200 response as quickly as possible. Perform heavy processing (fetching full analysis results, updating your database, etc.) asynchronously after acknowledging receipt.

Signature verification

Every webhook request includes an X-Shelfforce-Signature header that you should verify to ensure the request is authentic and has not been tampered with. The header format is:

X-Shelfforce-Signature: t=1740312618,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Where:

t — Unix timestamp of when the webhook was sent
v1 — HMAC-SHA256 signature

How to verify

Extract the t (timestamp) and v1 (signature) values from the header.
Construct the signed payload: {timestamp}.{raw_json_body}
Compute HMAC-SHA256 of that payload using your webhook secret.
Compare your computed signature with the v1 value using a constant-time comparison.
Optionally, reject requests where the timestamp is more than 5 minutes old to prevent replay attacks.

Standalone verification functions

If you already have a web server and just need the verification logic:

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signatureHeader: string,
  secret: string,
  toleranceSeconds = 300
): boolean {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => {
      const [key, value] = part.split("=");
      return [key, value];
    })
  );

  const timestamp = parts["t"];
  const signature = parts["v1"];

  if (!timestamp || !signature) {
    return false;
  }

  // Check timestamp tolerance (prevent replay attacks)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > toleranceSeconds) {
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(signedPayload)
    .digest("hex");

  // Constant-time comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

import hmac
import hashlib
import time

def verify_webhook_signature(
    payload: str,
    signature_header: str,
    secret: str,
    tolerance_seconds: int = 300,
) -> bool:
    # Parse the signature header
    parts = dict(part.split("=", 1) for part in signature_header.split(","))
    timestamp = parts.get("t")
    signature = parts.get("v1")

    if not timestamp or not signature:
        return False

    # Check timestamp tolerance
    now = int(time.time())
    if abs(now - int(timestamp)) > tolerance_seconds:
        return False

    # Compute expected signature
    signed_payload = f"{timestamp}.{payload}"
    expected = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256,
    ).hexdigest()

    # Constant-time comparison
    return hmac.compare_digest(signature, expected)

Retry behavior

If your webhook endpoint returns a non-2xx status code or is unreachable, Shelfforce retries the delivery up to 3 times with exponential backoff:

Attempt	Delay
1st retry	500ms
2nd retry	1 second
3rd retry	2 seconds

After all retries are exhausted, the webhook delivery is marked as failed. You can view failed deliveries in the Developers page in the dashboard.

Managing webhooks

Operation	Endpoint	Key role
List webhooks	`GET /api/v1/webhooks`	`admin`
Create webhook	`POST /api/v1/webhooks`	`admin`
Delete webhook	`DELETE /api/v1/webhooks/{id}`	`admin`

List webhooks

curl https://shelfforce.ai/api/v1/webhooks \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

response = requests.get(
    "https://shelfforce.ai/api/v1/webhooks",
    headers={"Authorization": "Bearer sf_live_a1b2c3d4..."},
)

webhooks = response.json()["data"]
for wh in webhooks:
    print(f"{wh['id']}: {wh['url']} ({wh['status']})")

const response = await fetch("https://shelfforce.ai/api/v1/webhooks", {
  headers: { "Authorization": "Bearer sf_live_a1b2c3d4..." },
});

const { data: webhooks } = await response.json();
webhooks.forEach((wh) => {
  console.log(`${wh.id}: ${wh.url} (${wh.status})`);
});

Delete a webhook

curl -X DELETE https://shelfforce.ai/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer sf_live_a1b2c3d4..."

response = requests.delete(
    "https://shelfforce.ai/api/v1/webhooks/wh_abc123",
    headers={"Authorization": "Bearer sf_live_a1b2c3d4..."},
)

await fetch("https://shelfforce.ai/api/v1/webhooks/wh_abc123", {
  method: "DELETE",
  headers: { "Authorization": "Bearer sf_live_a1b2c3d4..." },
});

Testing

Use a tool like webhook.site to get a temporary URL for testing:

Go to webhook.site and copy the unique URL.
Register it as a webhook endpoint with events: ["*"].
Submit a test analysis via the API.
Watch the event appear on webhook.site with the full payload and headers.

Remember to delete test webhooks when you are done testing to avoid unnecessary deliveries.

Getting Started

Core Concepts

Guides

Available events

Registering a webhook

Webhook delivery format

HTTP headers

JSON body structure

Payload examples by event type

Webhook receiver examples

Signature verification

How to verify

Standalone verification functions

Retry behavior

Managing webhooks

List webhooks

Delete a webhook

Testing

​Available events

​Registering a webhook

​Webhook delivery format

​HTTP headers

​JSON body structure

​Payload examples by event type

​Webhook receiver examples

​Signature verification

​How to verify

​Standalone verification functions

​Retry behavior

​Managing webhooks

​List webhooks

​Delete a webhook

​Testing

Available events

Registering a webhook

Webhook delivery format

HTTP headers

JSON body structure

Payload examples by event type

Webhook receiver examples

Signature verification

How to verify

Standalone verification functions

Retry behavior

Managing webhooks

List webhooks

Delete a webhook

Testing