Skip to main content
An integration that mirrors a WISEPIM catalog needs to learn three things: which products are new, which changed and which are gone. Re-reading the whole catalog on every run works, but it is slow and wastes your rate limit. The API gives you three cheaper tools for this, and a reliable sync uses all three. Use webhooks for speed and polling for correctness. A webhook tells you within seconds that something changed. A periodic poll catches whatever the webhook did not announce.
1

Take a full snapshot once

Page through GET /products to the end. Record the time you started as both your updated_since and your deletion since watermark.
2

Subscribe a webhook

Create a webhook for product.created, product.updated and product.deleted. When a delivery arrives, verify it, store it and answer 2xx. A worker then reads the listed products with GET /products?ids=... and applies them, or removes the deleted ones.
3

Reconcile on a schedule

Every 15 to 60 minutes, drain GET /products?updated_since=<watermark> and GET /products/deleted?since=<watermark>, then apply what you find. Advance the two watermarks differently:
  • Products: set the next updated_since to the time this poll started, minus a safety margin of a few minutes. Do not use the highest updated_at you saw. The reason is explained below.
  • Deletions: set the next since to the highest deleted_at you saw.
Applying a change twice must be harmless, because the poll and the webhook will often report the same product.
4

Catch up after an outage

If your receiver was down long enough for deliveries to be given up, or WISEPIM switched the subscription off, run the reconciliation poll immediately. Events from that period are not replayed.
Run the reconciliation poll at least once a day even if webhooks look healthy. The deletion feed keeps deletions for 30 days. If your watermark falls further behind, the feed refuses it with since_too_old and you have to compare full product lists instead.
Both feeds need the products:read scope. Managing webhooks needs the webhooks:* scopes described below.

Poll for changes with updated_since

updated_since is an ISO-8601 timestamp and is inclusive: it returns products modified at or after that instant. Page with cursor until has_more is false.
GET /products pages by product id, not by updated_at. While you page through higher ids, a product with a lower id can change. That change is not in this drain, because you already passed its id. If you then store the highest updated_at you saw, the next poll starts after that change and skips it for good.Store the time the poll started instead, and subtract a safety margin before you send it as the next updated_since. The margin covers clock differences between your server and WISEPIM. Re-reading a product is harmless, so a generous margin costs little. Unlike the deletion feed, updated_since has no built-in overlap.

The deletion feed

GET /products?updated_since= can never return a product that has been deleted. GET /products/deleted fills that gap: it lists what was deleted from the project, oldest deletion first.
How the feed behaves:
  • since is inclusive and overlaps. The feed returns deletions at or after since, and also deletions up to 10 minutes before it. A deletion is time-stamped before its database transaction commits, so a slow delete can appear with a time older than one you already stored. The overlap catches it. Expect to see some deletions twice, and make applying a deletion idempotent.
  • Page, then advance. Page with cursor until has_more is false, then send the highest deleted_at you saw as the next since. The cursor is opaque and only valid on this route; a malformed one is 422 invalid_cursor.
  • 30-day retention. A since older than 30 days is 422 since_too_old. The error body carries oldest_available and retention_days. Re-read the full product list and compare it to yours instead. Without since, the feed starts at the oldest deletion it still holds.
  • Match on id, not sku. sku is the SKU the product had when it was deleted. A later product can reuse that SKU, so deleting by SKU could remove the new product from your system. sku is null for deletions recorded before the feed started storing SKUs in November 2026.
  • What appears. Single deletes, bulk deletes, variants removed together with their parent and deletes made by imports all appear. Deleting a whole project does not.
  • limit defaults to 50 and is capped at 200. A since that is not a valid ISO-8601 timestamp is 422 invalid_filter.

Webhooks

A webhook is a subscription that belongs to one project. When products in that project are created, updated or deleted, WISEPIM sends a signed POST to your URL. The body names the products and what changed. It never contains product content, so your receiver reads the products through the API afterwards.

Scopes and who can manage webhooks

Creating or changing a subscription also needs products:read, because a subscription sends product ids and SKUs to an outside system. webhooks:write and webhooks:delete follow the Manage integrations grant of the person who created the API key. Owners and admins have it, and so does a custom role with that grant. Built-in editors do not.
  • A person without the grant cannot create a key with these scopes (403 scope_permission_denied).
  • If the person loses the grant later, their key is refused on these routes with 403 issuer_permission_denied and required_permissions: ["manage_integrations"].
See scopes for the full list.

Create a webhook

The 201 response is the subscription plus its signing secret:
signing_secret appears only in this response. WISEPIM stores it encrypted and never returns it from a read. Store it in your secrets manager now. A replay of the same request with the same Idempotency-Key returns signing_secret: null. If you lost the secret, rotate it.
Rules for the request:
  • url must use https and resolve to a public internet host. It can be up to 1,024 ASCII characters. Private, loopback, link-local and cloud metadata addresses, URLs with credentials in them and hosts that do not resolve are refused with 422 invalid_webhook_url. The body carries a reason: malformed, https_required, unresolvable or not_public. The same check runs again on every delivery, so a hostname that is later pointed at a private address stops receiving.
  • events takes one or more of the three event types. Anything else is 422 invalid_events, and the error lists the allowed values.
  • description is an optional label of up to 255 characters. is_active defaults to true.
  • A project holds at most 10 webhooks (409 webhook_limit_reached), and each URL can be subscribed once per project (409 webhook_url_conflict). The error usually carries the existing webhook_id. When two requests race, it can come without one; find the webhook with GET /webhooks. Subscribe one URL to all the events it needs instead of creating one webhook per event.
A new subscription starts receiving events within about a minute.
There is no endpoint that sends a test event. To test a receiver on your own machine, expose it through a public https tunnel, because localhost and private addresses are refused with not_public. Create the webhook for the tunnel URL, wait about a minute, then change a test product, for example with PATCH /products/{product_id}. That triggers a product.updated delivery. Check the result in the delivery log.

Rotate the signing secret

POST /webhooks/{webhook_id}/rotate-secret replaces the secret and returns the new one once, in the same shape as the create response.
The old secret stops signing immediately. Every delivery sent after the call, including retries of older deliveries, carries a signature made with the new secret. To rotate without rejecting deliveries, let your receiver accept a list of secrets: add the new secret next to the old one, rotate, deploy, then remove the old one. The verification code below accepts a list for this reason.

Update, pause and delete

PATCH /webhooks/{webhook_id} changes url, events, description or is_active. Send only the fields you want to change; null is refused with 422 invalid_webhook.
  • "is_active": false pauses the subscription. Deliveries that were still waiting are discarded, not kept for later.
  • "is_active": true switches it back on, including a subscription WISEPIM switched off, and clears its failure state.
  • Re-enabling it or changing its url makes the person who created the calling API key the owner of the subscription. See issuer_revoked for why that matters.
DELETE /webhooks/{webhook_id} removes the subscription and its delivery log. Nothing more is sent to it.

What a delivery looks like

Each delivery is one POST for one event type and carries up to 500 products.
The body fields: Treat changed_fields as a hint for deciding what to re-read. An empty list means “re-read the product”. Read current content with GET /products?ids=4209,4210, which takes up to 200 comma-separated ids per call.

Batching and coalescing

WISEPIM collects changes for about 10 seconds before it builds deliveries, and merges them per product within that window.
  • Ten edits to one product in a few seconds arrive as one item, with the changed_fields of all ten combined.
  • A 10,000-product import arrives as tens of deliveries of up to 500 products, not as 10,000 requests.
  • If a product is created and then updated in the same window, you only get product.created.
  • If a product is updated and then deleted in the same window, you only get product.deleted.
  • A product created and deleted in the same window can appear in both a product.created and a product.deleted delivery. Reading it then returns nothing; that is expected.
Deliveries for one subscription go out one at a time, oldest first. Because the body never carries content, always read the current state of the product rather than relying on delivery order.

Verify the signature

Anyone who learns your URL can send it requests. The signature proves a delivery came from WISEPIM and was not altered on the way. The signature is the hex HMAC-SHA256, keyed with your signing secret, of this string followed by the raw request body bytes:
Note the trailing dot before the body. Three rules:
  1. Verify before parsing. Compute the signature over the exact bytes you received. Parsing the JSON and serialising it again changes the bytes and breaks the check.
  2. Compare in constant time. Use hmac.compare_digest or crypto.timingSafeEqual, never ==.
  3. Reject old timestamps. Refuse a delivery whose timestamp is more than 5 minutes away from your clock. This stops a captured request from being replayed later. Keep your server clock synchronised with NTP.
Answer a failed check with 401 and do nothing else. A 401 counts as a failed delivery, so a misconfigured secret shows up quickly in the delivery log.

Receive deliveries

WISEPIM waits at most 10 seconds in total for your answer, from opening the connection to receiving your response headers. A receiver that answers slowly, or sends its answer a little at a time, fails with timeout after 10s. So the receiver should do as little as possible:
  1. Verify the signature.
  2. Store the delivery, keyed by its event id, in a durable queue or an inbox table.
  3. Answer 2xx. Any status from 200 to 299 counts as delivered; the response body is ignored.
  4. Process the stored delivery in a separate worker.
Deliveries are at least once. A delivery can arrive again, for example when your 2xx was lost on the network. The event id is the same on every retry, so store it with a unique constraint and ignore a second copy. Your worker should also tolerate the same product appearing in several deliveries, and in your reconciliation poll. A minimal receiver, using the verification function above:
The worker then handles each stored delivery:
  • product.created and product.updated: read the ids in batches of up to 200 with GET /products?ids=... and upsert them by id. A product deleted in the meantime does not come back; its deletion arrives separately.
  • product.deleted: remove the products by id, not by sku.
Do not put a redirect in front of your receiver. WISEPIM never follows redirects; a 3xx answer counts as a failed delivery. Point the webhook at the final https URL.

Retries and backoff

A delivery fails when there is no answer, the answer takes longer than 10 seconds, the answer is a redirect or the status is anything other than 2xx. After a failure, the whole subscription pauses before WISEPIM tries again, and later deliveries wait behind the failed one. The pause grows with each consecutive failure: One successful delivery resets the count. A single delivery is given up after 8 attempts. The count belongs to the subscription, not to the delivery. If the subscription was healthy before the delivery first failed, the 8 attempts take about 8 hours. While the subscription keeps failing, the count stays at 7 or more, so later deliveries are tried every 4 hours and each one can take more than a day to be given up. A given-up delivery has status: failed in the delivery log and is not sent again; WISEPIM then moves on to the next one. Recover the changes it carried with the reconciliation poll.

Automatic disabling

WISEPIM switches a subscription off, sets is_active to false and records disabled_reason and disabled_at when one of these happens: The owner is the person who created the API key that created the subscription, or that last re-enabled it or changed its url. When a subscription is switched off, the deliveries it still owed are discarded. To recover:
1

Find the cause

Read GET /webhooks/{webhook_id} for disabled_reason, last_response_code and last_failure_at, and check the delivery log for last_error.
2

Fix it

Bring the endpoint back, correct the secret or URL, or, for issuer_revoked, use a key created by someone who has the Manage integrations grant.
3

Re-enable

This clears the failure state and makes your key’s creator the owner. Deliveries start again within about a minute.
4

Catch up

Events from the time the subscription was off are not replayed. Run GET /products?updated_since= and GET /products/deleted from your last watermark.

The delivery log

GET /webhooks/{webhook_id}/deliveries lists the deliveries of one subscription, oldest first, for the last 30 days. Filter with status=pending, status=delivered or status=failed.
id is the event id, the same value as the X-WisePIM-Event-Id header. The log shows counts and status, not the products a delivery carried. last_error is a short code: last_error never contains the resolved IP address of your endpoint.

What webhooks do not guarantee

A webhook is a notification, not the record. Keep the reconciliation poll running, because:
  • Some bulk paths, such as certain importers and background jobs, write products without announcing the change.
  • In rare cases WISEPIM’s internal cache loses track of which projects have webhooks. Changes made in the following minute or so are not announced until it recovers.
  • A new or re-enabled subscription starts receiving within about a minute. Changes in that minute may not be announced.
  • Deliveries that were given up, or discarded when a subscription was paused or switched off, are never resent.
  • Deleting a whole project sends nothing.

Common errors

Products and variants

Read and write the products your webhook tells you about.

Imports and exports

Move whole catalogs in files when a per-product sync is not enough.

Authentication and scopes

Create a key with the webhook and product scopes this page needs.

API introduction

Paging, errors, rate limits and idempotency for every endpoint.