Catalog Webhooks

Receive real-time push notifications when your product catalog changes. Instead of polling /v2/catalog, register a webhook endpoint and your backend is notified immediately when products, options, categories, or groups are created, updated, or deleted.

Overview

IIMMPACT ──POST──▶ Your Webhook URL
                     │
                     ├── Verify X-Webhook-Signature (HMAC-SHA256)
                     ├── Process event (upsert/delete in your DB)
                     └── Return 200 OK

• One event per request — each HTTP POST contains a single event
• Signed with HMAC-SHA256 — verify every request using your webhook secret
• Automatic retries — failed deliveries are retried with exponential backoff

Setup

Catalog webhooks are configured via the IIMMPACT Dashboard:

1. Go to Developer > Webhooks > Settings
2. Under Catalog Webhooks, enter your HTTPS webhook URL
3. Click Register — your webhook secret is shown once. Store it securely.
4. Use the secret to verify incoming webhook signatures

HTTPS Required

Your webhook URL must use HTTPS. HTTP endpoints are rejected.

From the same page you can also:

• Enable/disable webhook delivery without removing configuration
• Rotate your webhook secret if compromised
• Remove your webhook configuration entirely

Events During Downtime

Events that occur while webhooks are disabled are not queued. When re-enabled, fetch /v2/catalog to sync any missed changes.

Event Types

Your webhook receives all event types automatically. Each HTTP request contains one event.

Event	Resource	Description
product.created	products	New product added
product.updated	products	Product details changed
product.deleted	products	Product deactivated
option.created	options	New option added
option.updated	options	Option details changed
option.deleted	options	Option deactivated
category.created	categories	New category added
category.updated	categories	Category details changed
category.deleted	categories	Category deactivated
group.created	groups	New group added
group.updated	groups	Group details changed
group.deleted	groups	Group deactivated

Handling Webhooks

A complete webhook handler should: verify the signature, process the event, and return 200 OK.

app.post("/iimmpact/catalog-webhook", async (req, res) => {
  // 1. Verify signature
  const signature = req.headers["x-webhook-signature"];
  if (!verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  // 2. Process event
  const { type, resource, id, data } = req.body;

  switch (type) {
    case "product.created":
    case "product.updated":
      await db.products.upsert({ id, ...data });
      break;

    case "product.deleted":
      await db.products.deactivate(id);
      break;

    case "option.created":
    case "option.updated":
      await db.options.upsert({ id, ...data });
      break;

    case "option.deleted":
      await db.options.deactivate(id);
      break;

    // Handle category.* and group.* similarly
  }

  // 3. Return 200 to acknowledge receipt
  res.status(200).send("OK");
});

Respond Quickly

Return 200 OK as fast as possible. If your processing is slow, accept the webhook, queue the work, and process asynchronously. Slow responses may be treated as failures and trigger retries.

Retry Policy

Failed deliveries are retried with exponential backoff. After 5 failed attempts, the event is dropped.

Attempt	Delay After Failure
1	Immediate
2	~1 minute
3	~2 minutes
4	~4 minutes
5	~8 minutes

Response	Retried?	Reason
5xx (server error)	Yes	Transient failure
408 (request timeout)	Yes	Transient failure
429 (too many requests)	Yes	Rate limited
Connection error / DNS failure	Yes	Network issue
4xx (except 408, 429)	No	Permanent failure

Permanent Failures

4xx responses (except 408 and 429) are treated as permanent failures and are not retried. Ensure your endpoint returns 200 on success and only returns 4xx for genuinely invalid requests (e.g. 401 for bad signatures).

For the full payload format, signature verification code, and detailed event schema, see the Catalog Webhook Events reference.