Webhooks

Outbound webhooks tell your storefront or service that something in the catalog changed. They come from the Headless connector: once installed, it POSTs each matching event to your URL, signed with HMAC-SHA256.

In the admin

1. Go to Catalog → Connectors. Under Available, find Headless and click Install.
2. Enter a Name and a Destination URL (a public https:// endpoint), then click Install.
3. Copy the secret shown under Signing secret — copy now, store it with your receiver, and click Done.
4. Under Installed, expand the connector by clicking its status line (it reads never synced on a new install). In Events, tick the groups you want: Products & variants, Categories, Brands, Content pages, Images & files, Modifiers, Related products, Imports & wipes. Click Save events.
5. In Deliveries, click Send test event to post a signed webhook.test event, then click show to see the last 50 attempts with their HTTP status.

With the API

Install with POST /v1/connectors:

curl -X POST https://api.minipim.com/v1/connectors \
  -H 'Authorization: Bearer pim_…' -H 'Content-Type: application/json' \
  -d '{ "type": "headless", "name": "Storefront",
        "config": { "destination_url": "https://shop.example.com/api/pim-webhook",
                    "secret": "at-least-16-characters-long" } }'

Change subscriptions with PATCH /v1/connectors/{id} and { "config": { "events": ["product.*", "category.*"] } }. Use GET /v1/connectors/{id}/deliveries for the delivery log and POST /v1/connectors/{id}/webhooks/test for a test event.

Each delivery is a POST with these headers and body:

Content-Type: application/json
X-MiniPim-Event: product.updated
X-MiniPim-Signature-256: sha256=<hex HMAC-SHA256 of the raw body>

{ "name": "product.updated", "organization_id": "…", "entity_id": "…",
  "actor": { "type": "user", "id": "…" }, "timestamp": "…",
  "payload": { "changed_fields": ["name"] } }

Verify the signature against the raw body bytes, not re-serialized JSON. The TypeScript SDK ships verifyMinipimWebhook (Node) and verifyMinipimWebhookEdge (Edge runtimes).

Events

The defaults for a new install are product.*, variant.*, category.*, brand.*, content_page.*, content_category.*, media.attached, media.detached, media.association_updated, media.deleted, modifier.updated, modifier.deleted, product_modifier.*, product_relationship.*, connector.sync.completed and catalog.wiped.

Payloads are deliberately small, such as changed_fields or a slug. Treat each event as a signal to re-fetch the entity from the API.

Rules and limits

• Deliveries are not retried. A timeout, non-2xx response or network error is logged and dropped. Make handlers idempotent and run a periodic catch-up with GET /v1/products?updatedSince=….
• Redirects are not followed. Your endpoint must answer 2xx directly.
• The destination must be http or https and must not be localhost or a loopback, private (RFC 1918), link-local or multicast address. This is checked at install and again at every delivery. Use a tunnel to test locally.
• The secret must be at least 16 characters. The admin generates one for you and shows it once.
• product.* matches by prefix including the dot, so it does not cover product_modifier.* or product_relationship.*.
• Connector pulls do not emit per-product events. They send one connector.sync.completed; a wipe sends catalog.wiped. Treat both as “revalidate everything”.
• Installs created before October 2026 keep the event list they were created with. Tick the newer groups (content pages, media, modifiers, related products) under Events to receive them.
• The delivery log keeps the 50 most recent attempts per connector.
• Optional extra_headers in the config are sent with every delivery, for example a static token your receiver expects.

These are outbound webhooks. Inbound webhooks, where BigCommerce notifies minipim of store changes, are covered in Connectors.