Webhook Payload Reference

When Catalogian detects a change in your source, it sends a POST request to your webhook endpoint with a JSON payload describing the delta event. This page documents every field.

Full payload example

{
  "event": "delta",
  "webhookId": "wh_a1b2c3d4",
  "sourceId": "cmmfyryl30005ygld7m5596gm",
  "sourceName": "Acme Product Feed",
  "sourceSlug": "acme-product-feed",
  "deltaEventId": "evt_01j8k9m2n3p4q5",
  "detectedAt": "2026-03-19T08:00:00.000Z",
  "summary": {
    "newCount": 14,
    "changedCount": 3,
    "deletedCount": 1,
    "unchangedCount": 49982,
    "totalCount": 50000
  },
  "newKeys": [
    "sku-9001", "sku-9002", "sku-9003", "sku-9004",
    "sku-9005", "sku-9006", "sku-9007", "sku-9008",
    "sku-9009", "sku-9010", "sku-9011", "sku-9012",
    "sku-9013", "sku-9014"
  ],
  "changedKeys": ["sku-1234", "sku-5678", "sku-4321"],
  "deletedKeys": ["sku-0042"]
}

Field reference

Field	Type	Description
`event`	string	Always `"delta"` — the event type
`webhookId`	string	The webhook endpoint ID that triggered this delivery
`sourceId`	string	The source ID
`sourceName`	string	Human-readable source name
`sourceSlug`	string	URL-friendly source identifier
`deltaEventId`	string	The delta event ID — use this to fetch row details via the API
`detectedAt`	string	ISO 8601 timestamp when the change was detected
`summary.newCount`	integer	Number of rows added since last check
`summary.changedCount`	integer	Number of rows with modified values
`summary.deletedCount`	integer	Number of rows removed since last check
`summary.unchangedCount`	integer	Number of rows with no changes
`summary.totalCount`	integer	Total rows in the current snapshot
`newKeys`	string[]	Key field values of added rows (max 100)
`changedKeys`	string[]	Key field values of changed rows (max 100)
`deletedKeys`	string[]	Key field values of removed rows (max 100)

Key array limits

The newKeys, changedKeys, and deletedKeys arrays include up to 100 keys each. If more than 100 rows changed in a category, the array is truncated. Use the delta rows API to get the complete list.

No-change events

Catalogian does not send webhooks for no-change events (when nothing changed). Webhooks only fire when at least one row was added, changed, or deleted.

Request headers

Every webhook request includes these headers:

Header	Value
`Content-Type`	`application/json`
`X-Catalogian-Event`	`delta`
`X-Catalogian-Delivery`	Unique delivery ID (for deduplication)
`X-Catalogian-Attempt`	Attempt number: 1, 2, or 3
`X-Catalogian-Signature`	`sha256=<hmac>` (only if signing secret is configured)

Using the payload

A typical webhook handler:

app.post("/webhooks/catalogian", async (req, res) => {
  const { event, sourceSlug, summary, deltaEventId } = req.body;

  // Quick acknowledge — process async
  res.status(200).send("OK");

  if (summary.changedCount > 0 || summary.newCount > 0) {
    // Fetch full row data from the API
    const rows = await fetch(
      `https://api.catalogian.com/v1/sources/${sourceSlug}/delta/${deltaEventId}/rows`,
      { headers: { Authorization: "Bearer " + process.env.CATALOGIAN_KEY } }
    ).then(r => r.json());

    // Process the changes...
    await syncToDatabase(rows);
  }
});

Secure your webhook endpoint. Verifying Signatures →