> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wisepim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks and change tracking

> Follow product creates, updates and deletes without re-reading the catalog: the updated_since filter, the deletion feed and signed webhooks, and how to combine them into a sync that never misses a change.

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.

| Tool | What it tells you | How fast | Can it miss something? |
| - | - | - | - |
| [`GET /products?updated_since=`](https://docs.wisepim.com/en/api-reference/products/list) | Products created or changed since a timestamp, with their full content | As often as you poll | No, but it cannot return a product that no longer exists |
| [`GET /products/deleted`](https://docs.wisepim.com/en/api-reference/products/list-deleted) | Products deleted since a timestamp (`id`, `sku`, `deleted_at`) | As often as you poll | No, for 30 days. Older history is gone |
| [Webhooks](#webhooks) | That products were created, updated or deleted: ids, SKUs and changed field names, never content | Usually seconds | Yes. Some bulk paths, a disabled subscription and a given-up delivery all leave gaps |

## 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`](https://docs.wisepim.com/en/api-reference/products/list) 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](#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](#poll-for-changes-with-updated_since).
* **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.

> [!TIP]
>
> 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](#scopes-and-who-can-manage-webhooks).

## 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`.

```bash theme={null}
curl "https://wisepim.com/api/public/v1/products?updated_since=2026-11-19T09:00:00Z&limit=200" \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

> [!WARNING]
>
> `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`](https://docs.wisepim.com/en/api-reference/products/list-deleted) fills that gap: it lists what was deleted from the project, oldest deletion first.

```bash theme={null}
curl "https://wisepim.com/api/public/v1/products/deleted?since=2026-11-19T09:00:00Z&limit=200" \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

```json theme={null}
{
  "data": [
    { "id": 4211, "sku": "TEE-ORG-M-BLK", "deleted_at": "2026-11-19T09:14:03.120000Z" },
    { "id": 4212, "sku": "TEE-ORG-L-BLK", "deleted_at": "2026-11-19T09:14:03.120000Z" }
  ],
  "next_cursor": "ZGVsOjIwMjYtMTEtMTlUMDk6MTQ6MDMuMTIwMDAwKzAwOjAwfDk4MTI",
  "has_more": true
}
```

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.

| Event | Sent when |
| - | - |
| `product.created` | A product is created |
| `product.updated` | Content, attribute values, category membership, family or variant structure changed |
| `product.deleted` | A product is deleted |

### Scopes and who can manage webhooks

| Endpoint | Required scopes |
| - | - |
| [`GET /webhooks`](https://docs.wisepim.com/en/api-reference/webhooks/list), [`GET /webhooks/{webhook_id}`](https://docs.wisepim.com/en/api-reference/webhooks/get), [`GET /webhooks/{webhook_id}/deliveries`](https://docs.wisepim.com/en/api-reference/webhooks/deliveries) | `webhooks:read` |
| [`POST /webhooks`](https://docs.wisepim.com/en/api-reference/webhooks/create), [`PATCH /webhooks/{webhook_id}`](https://docs.wisepim.com/en/api-reference/webhooks/update), [`POST /webhooks/{webhook_id}/rotate-secret`](https://docs.wisepim.com/en/api-reference/webhooks/rotate-secret) | `webhooks:write` and `products:read` |
| [`DELETE /webhooks/{webhook_id}`](https://docs.wisepim.com/en/api-reference/webhooks/delete) | `webhooks:delete` |

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](https://docs.wisepim.com/en/api-reference/authentication.md#scopes) for the full list.

### Create a webhook

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/webhooks \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: erp-webhook-setup-2026-11-20" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.example.com/hooks/wisepim",
    "events": ["product.created", "product.updated", "product.deleted"],
    "description": "ERP product sync"
  }'
```

The `201` response is the subscription plus its signing secret:

```json theme={null}
{
  "id": 5,
  "url": "https://erp.example.com/hooks/wisepim",
  "description": "ERP product sync",
  "events": ["product.created", "product.updated", "product.deleted"],
  "is_active": true,
  "disabled_reason": null,
  "disabled_at": null,
  "consecutive_failures": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "last_response_code": null,
  "created_at": "2026-11-20T10:02:11.481000Z",
  "updated_at": "2026-11-20T10:02:11.481000Z",
  "signing_secret": "whsec_3qL0bX9nV2rTq8mWc7Yp1sKdE4uHf6GzJa5NoRi0tBk"
}
```

> [!WARNING]
>
> `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](#rotate-the-signing-secret).

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`](https://docs.wisepim.com/en/api-reference/webhooks/list). 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.

> [!TIP]
>
> 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}`](https://docs.wisepim.com/en/api-reference/products/update). That triggers a `product.updated` delivery. Check the result in the [delivery log](#the-delivery-log).

### Rotate the signing secret

[`POST /webhooks/{webhook_id}/rotate-secret`](https://docs.wisepim.com/en/api-reference/webhooks/rotate-secret) replaces the secret and returns the new one once, in the same shape as the create response.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/webhooks/5/rotate-secret \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: erp-webhook-rotate-2026-11-20"
```

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}`](https://docs.wisepim.com/en/api-reference/webhooks/update) 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`](#automatic-disabling) for why that matters.

[`DELETE /webhooks/{webhook_id}`](https://docs.wisepim.com/en/api-reference/webhooks/delete) 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**.

```http theme={null}
POST /hooks/wisepim HTTP/1.1
Host: erp.example.com
Content-Type: application/json
User-Agent: WisePIM-Webhooks/1.0
X-WisePIM-Event-Id: 6f1c1f0e-3b7a-4c53-9d0c-2f6f8f1f6b1a
X-WisePIM-Event-Type: product.updated
X-WisePIM-Timestamp: 1795169644
X-WisePIM-Delivery-Attempt: 1
X-WisePIM-Signature: v1=8c1f0d2a6b9e4f7c3a5d8e1b0f2c4a6d9e8b7c5a3f1d0e2b4c6a8f9d7e5c3b1a

{"id":"6f1c1f0e-3b7a-4c53-9d0c-2f6f8f1f6b1a","type":"product.updated","created_at":"2026-11-20T10:14:03.120000+00:00","project_id":12,"webhook_id":5,"data":[{"id":4209,"sku":"TEE-ORG-S-BLK","occurred_at":"2026-11-20T10:13:55.002000+00:00","changed_fields":["attributes","description"]},{"id":4210,"sku":"TEE-ORG-S-WHT","occurred_at":"2026-11-20T10:13:55.002000+00:00","changed_fields":["name"]}]}
```

| Header | Meaning |
| - | - |
| `X-WisePIM-Event-Id` | Unique id of this delivery. It stays the same on every retry. Use it to deduplicate. |
| `X-WisePIM-Event-Type` | `product.created`, `product.updated` or `product.deleted` |
| `X-WisePIM-Timestamp` | Unix seconds when this attempt was signed. It changes on every retry. |
| `X-WisePIM-Delivery-Attempt` | `1` on the first attempt, then counts up |
| `X-WisePIM-Signature` | `v1=` followed by the hex HMAC-SHA256 signature |

The body fields:

| Field | Meaning |
| - | - |
| `id`, `type` | The same values as the event id and event type headers |
| `created_at` | When WISEPIM built this delivery |
| `project_id`, `webhook_id` | The project and subscription it belongs to |
| `data[].id` | The product id. Use it to read or delete the product. |
| `data[].sku` | The product's SKU. It can be `null` when the product was deleted before the delivery was built. |
| `data[].occurred_at` | The latest change to this product that the delivery covers |
| `data[].changed_fields` | Only on `product.updated`. Column names such as `name` or `description`, plus `attributes`, `categories`, `family` and `variant_axes`. At most 50 names. |

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`](https://docs.wisepim.com/en/api-reference/products/list), 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**:

```text theme={null}
{X-WisePIM-Timestamp}.{X-WisePIM-Event-Id}.{X-WisePIM-Event-Type}.
```

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.

```python Python theme={null}
import hashlib
import hmac
import os
import time

# Comma-separated, so you can hold the old and new secret during a rotation.
SIGNING_SECRETS = [s for s in os.environ["WISEPIM_WEBHOOK_SECRETS"].split(",") if s]
TOLERANCE_SECONDS = 300


def verify_wisepim_signature(headers, raw_body: bytes) -> bool:
    """True when the delivery was signed by WISEPIM with one of our secrets.

    `headers` must be case-insensitive (Flask, Django and Starlette headers are).
    `raw_body` must be the exact bytes received, before any JSON parsing.
    """
    timestamp = headers.get("X-WisePIM-Timestamp", "")
    event_id = headers.get("X-WisePIM-Event-Id", "")
    event_type = headers.get("X-WisePIM-Event-Type", "")
    signature = headers.get("X-WisePIM-Signature", "")
    if not (timestamp.isdigit() and event_id and event_type and signature):
        return False
    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False

    signed = f"{timestamp}.{event_id}.{event_type}.".encode() + raw_body
    received = signature.encode()
    for secret in SIGNING_SECRETS:
        digest = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
        if hmac.compare_digest(f"v1={digest}".encode(), received):
            return True
    return False
```

```javascript Node.js theme={null}
import crypto from "node:crypto";

// Comma-separated, so you can hold the old and new secret during a rotation.
const SIGNING_SECRETS = (process.env.WISEPIM_WEBHOOK_SECRETS ?? "")
  .split(",")
  .filter(Boolean);
const TOLERANCE_SECONDS = 300;

/**
 * True when the delivery was signed by WISEPIM with one of our secrets.
 * `headers` uses Node's lower-case header names (req.headers).
 * `rawBody` must be the exact Buffer received, before any JSON parsing.
 */
export function verifyWisepimSignature(headers, rawBody) {
  const timestamp = headers["x-wisepim-timestamp"] ?? "";
  const eventId = headers["x-wisepim-event-id"] ?? "";
  const eventType = headers["x-wisepim-event-type"] ?? "";
  const signature = headers["x-wisepim-signature"] ?? "";
  if (!/^\d+$/.test(timestamp) || !eventId || !eventType || !signature) {
    return false;
  }
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) {
    return false;
  }

  const signed = Buffer.concat([
    Buffer.from(`${timestamp}.${eventId}.${eventType}.`, "utf8"),
    rawBody,
  ]);
  const received = Buffer.from(signature, "utf8");
  return SIGNING_SECRETS.some((secret) => {
    const digest = crypto.createHmac("sha256", secret).update(signed).digest("hex");
    const expected = Buffer.from(`v1=${digest}`, "utf8");
    return expected.length === received.length && crypto.timingSafeEqual(expected, received);
  });
}
```

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](#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:

```python Python (Flask) theme={null}
import json

from flask import Flask, abort, request

from wisepim_signature import verify_wisepim_signature  # the function above

app = Flask(__name__)


def store_in_inbox(event: dict) -> None:
    """Insert into a table whose primary key is event["id"].

    Ignore a unique-key conflict: that is a retry of a delivery you already have.
    A worker reads the inbox, fetches the products and applies them.
    """
    ...


@app.post("/hooks/wisepim")
def wisepim_webhook():
    raw_body = request.get_data()  # raw bytes, before any parsing
    if not verify_wisepim_signature(request.headers, raw_body):
        abort(401)
    store_in_inbox(json.loads(raw_body))
    return "", 204
```

```javascript Node.js (Express) theme={null}
import express from "express";
import { verifyWisepimSignature } from "./wisepim-signature.js"; // the function above

const app = express();

async function storeInInbox(event) {
  // Insert into a table whose primary key is event.id.
  // Ignore a unique-key conflict: that is a retry of a delivery you already have.
  // A worker reads the inbox, fetches the products and applies them.
}

// express.raw keeps the body as a Buffer. Raise the limit: a delivery of
// 500 updated products with many changed fields can exceed Express's
// 100 kB default.
app.post(
  "/hooks/wisepim",
  express.raw({ type: "application/json", limit: "5mb" }),
  async (req, res) => {
    if (!verifyWisepimSignature(req.headers, req.body)) {
      return res.sendStatus(401);
    }
    await storeInInbox(JSON.parse(req.body.toString("utf8")));
    res.sendStatus(204);
  },
);

app.listen(3000);
```

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`.

> [!WARNING]
>
> 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:

| Consecutive failures | Pause before the next attempt |
| - | - |
| 1 | 30 seconds |
| 2 | 2 minutes |
| 3 | 10 minutes |
| 4 | 30 minutes |
| 5 | 1 hour |
| 6 | 2 hours |
| 7 and more | 4 hours |

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:

| `disabled_reason` | Cause |
| - | - |
| `delivery_failures` | 20 failed attempts in a row, and the subscription has been failing for at least 3 days |
| `backlog_full` | More than 1,000 deliveries are waiting while the subscription is failing. A healthy subscription draining a large import is not affected. |
| `endpoint_gone` | Your endpoint answered `410 Gone`. This disables the subscription at once, so only send `410` when you want it switched off. |
| `issuer_revoked` | The person who owns the subscription no longer has access to the project, was deactivated or lost the Manage integrations grant |

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}`](https://docs.wisepim.com/en/api-reference/webhooks/get) for `disabled_reason`, `last_response_code` and `last_failure_at`, and check the [delivery log](#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**

```bash theme={null}
curl -X PATCH https://wisepim.com/api/public/v1/webhooks/5 \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: erp-webhook-reenable-2026-11-20" \
  -H "Content-Type: application/json" \
  -d '{"is_active": true}'
```

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`](https://docs.wisepim.com/en/api-reference/webhooks/deliveries) lists the deliveries of one subscription, oldest first, for the last **30 days**. Filter with `status=pending`, `status=delivered` or `status=failed`.

```bash theme={null}
curl "https://wisepim.com/api/public/v1/webhooks/5/deliveries?status=failed" \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "6f1c1f0e-3b7a-4c53-9d0c-2f6f8f1f6b1a",
      "event_type": "product.updated",
      "status": "failed",
      "attempts": 8,
      "item_count": 2,
      "last_response_code": 503,
      "last_error": "HTTP 503",
      "created_at": "2026-11-20T10:14:03.120000Z",
      "last_attempt_at": "2026-11-20T18:01:44.508000Z",
      "delivered_at": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

`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` | Meaning |
| - | - |
| `HTTP 503` (any status) | Your endpoint answered with a non-`2xx` status |
| `timeout after 10s` | No complete answer within 10 seconds |
| `unreachable: ConnectError` (or another error name) | The connection failed: DNS, TLS, a refused or reset connection |
| `refused: not_public`, `refused: unresolvable`, `refused: https_required` | The URL failed the delivery-time safety check |
| `refused: redirects are not followed` | Your endpoint answered with a redirect (`301`, `302`, `303`, `307` or `308`). `last_response_code` is `null` in this case. Point the webhook at the final URL. |
| `delivery aborted` | The attempt was cut off on WISEPIM's side; it counts as a failure and is retried |
| `subscription_inactive` | Discarded because the subscription was paused |
| `subscription_disabled:<reason>` | Discarded because WISEPIM switched the subscription off |

`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

| Status | Code | Cause | What to do |
| - | - | - | - |
| `401` | `api_key_required` | Missing, revoked or expired API key | Check the `Authorization` header and the key in [API Access](https://docs.wisepim.com/en/settings/api.md) |
| `403` | `insufficient_scope` | The key lacks `webhooks:*` or `products:read` | Create a key with the scopes in [the table above](#scopes-and-who-can-manage-webhooks) |
| `403` | `issuer_cannot_write` | On `webhooks:write` and `webhooks:delete` routes: the person who created the key can no longer edit the project, for example after becoming a viewer | Use a key created by a member who can edit the project and holds Manage integrations |
| `403` | `issuer_permission_denied` | The key's creator no longer has the Manage integrations grant | Use a key created by an owner, admin or a role with that grant |
| `403` | `scope_permission_denied` | Creating a key with `webhooks:write` or `webhooks:delete` without the Manage integrations grant | Ask an owner or admin to create the key |
| `404` | `not_found` | Unknown webhook id, or one in another project | Check the id with `GET /webhooks` |
| `409` | `webhook_limit_reached` | The project already has 10 webhooks | Delete one, or subscribe one URL to several events |
| `409` | `webhook_url_conflict` | That URL is already subscribed in this project | Update the existing webhook instead. Its `webhook_id` is usually in the error; if not, find it with `GET /webhooks` |
| `409` | `idempotency_conflict` | An `Idempotency-Key` was reused for a different request | Use a new key per logical operation |
| `422` | `invalid_webhook_url` | Not `https`, not public, unresolvable or malformed (see `reason`) | Use a public `https` URL with no credentials and no redirect |
| `422` | `invalid_events` | An unknown event type | Use only the values in `allowed` |
| `422` | `invalid_webhook` | A field was sent as `null` in a `PATCH` | Leave out fields you do not want to change |
| `422` | `since_too_old` | The deletion feed `since` is older than 30 days | Re-read the full product list, then restart the feed from `oldest_available` or later |
| `422` | `invalid_filter` | `since` is not ISO-8601, or `status` is not `pending`, `delivered` or `failed` | Fix the query parameter |
| `422` | `invalid_cursor` | A cursor from another route, or an altered one | Pass `next_cursor` back unchanged |
| `429` | `rate_limited` | Over the key's request limit | Wait for `Retry-After`, then retry |

## Related

> [card] [Products and variants](https://docs.wisepim.com/en/api-reference/products-and-variants.md)
>
> Read and write the products your webhook tells you about.

> [card] [Imports and exports](https://docs.wisepim.com/en/api-reference/imports-and-exports.md)
>
> Move whole catalogs in files when a per-product sync is not enough.

> [card] [Authentication and scopes](https://docs.wisepim.com/en/api-reference/authentication.md)
>
> Create a key with the webhook and product scopes this page needs.

> [card] [API introduction](https://docs.wisepim.com/en/api-reference/introduction.md)
>
> Paging, errors, rate limits and idempotency for every endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.