API Documentation
Try Demo Home
Webhooks

React to changes in real time

Subscribe to entity lifecycle events and receive POST notifications when products are created, updated, deleted, or transition between states. Build reactive integrations without polling.

Available Events

Event Triggered when
entity.created A new entity (product record) is created
entity.updated An entity's attribute values are updated
entity.deleted An entity is deleted
entity.transition An entity transitions between lifecycle states (e.g. Draft to Review)
variant.created A new variant is created under an entity
variant.updated A variant's attribute values are updated
variant.deleted A variant is deleted

HMAC Verification

If a secret is set, each delivery includes an X-Sigma-Signature header containing an HMAC-SHA256 of the request body. Verify it to ensure authenticity.

Retry Policy

Failed deliveries (non-2xx responses) are retried up to 3 times with exponential backoff: 10s, 60s, 300s.

Idempotency

Each webhook delivery includes a unique deliveryId. Use it to deduplicate in case of retries.

Active/Inactive

Set active: false to pause a webhook without deleting its configuration. Re-enable at any time.

Endpoints

Method Endpoint Description
GET /webhooks List all webhooks
GET /webhooks/:id Get webhook by ID
POST /webhooks Create a new webhook
PUT /webhooks/:id Update a webhook
DELETE /webhooks/:id Delete a webhook

List all webhooks

Returns all configured webhooks for the current tenant.

curl https://api.sigma-pim.com/api/v1/webhooks \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
// Response [ { "id": "wh-sync-notify", "name": "Sync Notifications", "description": "Notify ERP when products change", "url": "https://erp.example.com/hooks/sigma-pim", "events": ["entity.created", "entity.updated", "entity.deleted"], "secret": "••••••••", "active": true }, { "id": "wh-lifecycle-slack", "name": "Lifecycle Alerts", "description": "Post to Slack on state transitions", "url": "https://hooks.slack.com/services/T00/B00/xxxx", "events": ["entity.transition"], "active": true } ]

Get webhook by ID

Returns a single webhook with its full configuration including subscribed events.

curl https://api.sigma-pim.com/api/v1/webhooks/wh-sync-notify \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Create webhook

Create a new webhook subscription. Specify the target URL, events to subscribe to, and an optional HMAC secret for signature verification.

Request body

Field Type Description
id string Unique identifier for the webhook
name string Human-readable name
description string? Optional description
url string Target URL to receive POST notifications
events string[] Events to subscribe to (see table above)
secret string? HMAC secret for signature verification
active boolean Whether the webhook is active
curl -X POST https://api.sigma-pim.com/api/v1/webhooks \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \ -H "Content-Type: application/json" \ -d '{ "id": "wh-sync-notify", "name": "Sync Notifications", "description": "Notify ERP when products change", "url": "https://erp.example.com/hooks/sigma-pim", "events": [ "entity.created", "entity.updated", "entity.deleted" ], "secret": "whsec_a1b2c3d4e5f6g7h8i9j0", "active": true }'
// Response { "id": "wh-sync-notify", "name": "Sync Notifications", "description": "Notify ERP when products change", "url": "https://erp.example.com/hooks/sigma-pim", "events": ["entity.created", "entity.updated", "entity.deleted"], "secret": "••••••••", "active": true }

Update webhook

Update an existing webhook. Send the full webhook object. You can change the subscribed events, URL, or toggle active status.

curl -X PUT https://api.sigma-pim.com/api/v1/webhooks/wh-sync-notify \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \ -H "Content-Type: application/json" \ -d '{ "id": "wh-sync-notify", "name": "Sync Notifications", "description": "Notify ERP when products change", "url": "https://erp.example.com/hooks/sigma-pim", "events": [ "entity.created", "entity.updated", "entity.deleted", "entity.transition", "variant.created", "variant.updated" ], "secret": "whsec_a1b2c3d4e5f6g7h8i9j0", "active": true }'

Delete webhook

Permanently delete a webhook. No further events will be delivered to the configured URL.

curl -X DELETE https://api.sigma-pim.com/api/v1/webhooks/wh-sync-notify \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
// Response { "deleted": true }

Webhook Payload Shape

When an event fires, Sigma PIM sends a POST request to the webhook URL with the following JSON payload. The data object varies by event type.

// POST https://erp.example.com/hooks/sigma-pim // Headers: // Content-Type: application/json // X-Sigma-Event: entity.updated // X-Sigma-Delivery: del-9f8e7d6c5b4a // X-Sigma-Signature: sha256=a1b2c3d4e5f6... { "event": "entity.updated", "deliveryId": "del-9f8e7d6c5b4a", "timestamp": "2026-03-08T10:05:30.000Z", "data": { "entityId": "ent-coastal-windbreaker", "schemaId": "schema-apparel", "changedAttributes": ["price", "description"], "lifecycleState": "published", "updatedBy": "user-admin" } }
// entity.transition payload { "event": "entity.transition", "deliveryId": "del-3a2b1c4d5e6f", "timestamp": "2026-03-08T11:00:00.000Z", "data": { "entityId": "ent-alpine-parka", "schemaId": "schema-apparel", "fromState": "draft", "toState": "review", "triggeredBy": "user-editor" } }

Verifying Signatures

If you provided a secret when creating the webhook, verify the X-Sigma-Signature header to ensure the request is authentic.

// Node.js verification example const crypto = require('crypto'); function verifySignature(body, signature, secret) { const expected = 'sha256=' + crypto.createHmac('sha256', secret) .update(body) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); }
Previous API Keys Next Errors