Catalog Webhook Events

Catalog webhooks deliver real-time notifications when your product catalog changes. Each HTTP POST request to your registered endpoint contains a single event signed with HMAC-SHA256.

For setup instructions and configuration, see the Catalog Webhooks Guide.

Event Types

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

Payload Format

{
  "type": "product.updated",
  "resource": "products",
  "id": "CELCOM10",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "product_code": "CELCOM10",
    "product_category_code": "MOBILE_PREPAID",
    "name": "Celcom Prepaid",
    "display_name": "Celcom Prepaid Reload",
    "image_url": "https://dashboard.iimmpact.com/img/CELCOM10.png",
    "processing_time": "instant",
    "is_active": true
  }
}

Field	Type	Description
type	string	Event type (e.g. product.updated, option.created)
resource	string	Resource kind: products, options, categories, groups
id	string	Identifier of the affected resource
timestamp	string	ISO 8601 timestamp of when the change occurred
data	object|null	Full resource data, or null for delete events

Delete Events

For *.deleted events, the data field is null. Use the id field to remove the resource from your local store.

Request Headers

Each webhook request includes these headers:

Header	Description
Content-Type	application/json
X-Webhook-Signature	HMAC-SHA256 signature: sha256=<hex>

Signature Verification

All webhook requests include an X-Webhook-Signature header. Always verify the signature before processing the event to confirm it originated from IIMMPACT and was not tampered with.

The header format is sha256=<hex_digest>, computed as HMAC-SHA256 of the raw request body using your webhook secret.

import crypto from "crypto";

function verifyWebhookSignature(
  rawBody: string,
  signature: string | null,
  secret: string,
): boolean {
  if (!signature) return false;

  const providedSig = signature.startsWith("sha256=")
    ? signature.slice(7)
    : signature;

  const expectedSig = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  try {
    return crypto.timingSafeEqual(
      Buffer.from(providedSig, "hex"),
      Buffer.from(expectedSig, "hex"),
    );
  } catch {
    return false;
  }
}

Use Raw Body

Verify the signature against the raw request body bytes, not a parsed-and-re-serialized JSON object. Re-serializing can change key order or whitespace, causing a mismatch.