Recommended sync design
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_sinceto the time this poll started, minus a safety margin of a few minutes. Do not use the highestupdated_atyou saw. The reason is explained below. - Deletions: set the next
sinceto the highestdeleted_atyou saw.
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.
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.
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.
sinceis inclusive and overlaps. The feed returns deletions at or aftersince, 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
cursoruntilhas_moreisfalse, then send the highestdeleted_atyou saw as the nextsince. The cursor is opaque and only valid on this route; a malformed one is422 invalid_cursor. - 30-day retention. A
sinceolder than 30 days is422 since_too_old. The error body carriesoldest_availableandretention_days. Re-read the full product list and compare it to yours instead. Withoutsince, the feed starts at the oldest deletion it still holds. - Match on
id, notsku.skuis 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.skuisnullfor 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.
limitdefaults to 50 and is capped at 200. Asincethat is not a valid ISO-8601 timestamp is422 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 signedPOST 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_deniedandrequired_permissions: ["manage_integrations"].
Create a webhook
201 response is the subscription plus its signing secret:
urlmust usehttpsand 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 with422 invalid_webhook_url. The body carries areason:malformed,https_required,unresolvableornot_public. The same check runs again on every delivery, so a hostname that is later pointed at a private address stops receiving.eventstakes one or more of the three event types. Anything else is422 invalid_events, and the error lists theallowedvalues.descriptionis an optional label of up to 255 characters.is_activedefaults totrue.- 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 existingwebhook_id. When two requests race, it can come without one; find the webhook withGET /webhooks. Subscribe one URL to all the events it needs instead of creating one webhook per event.
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.
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": falsepauses the subscription. Deliveries that were still waiting are discarded, not kept for later."is_active": trueswitches it back on, including a subscription WISEPIM switched off, and clears its failure state.- Re-enabling it or changing its
urlmakes the person who created the calling API key the owner of the subscription. Seeissuer_revokedfor 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 onePOST 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_fieldsof 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.createdand aproduct.deleteddelivery. Reading it then returns nothing; that is expected.
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:- 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.
- Compare in constant time. Use
hmac.compare_digestorcrypto.timingSafeEqual, never==. - 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.
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 withtimeout after 10s. So the receiver should do as little as possible:
- Verify the signature.
- Store the delivery, keyed by its event id, in a durable queue or an inbox table.
- Answer
2xx. Any status from 200 to 299 counts as delivered; the response body is ignored. - Process the stored delivery in a separate worker.
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:
product.createdandproduct.updated: read the ids in batches of up to 200 withGET /products?ids=...and upsert them byid. A product deleted in the meantime does not come back; its deletion arrives separately.product.deleted: remove the products byid, not bysku.
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 than2xx. 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, setsis_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
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
Related
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.

