Integrations and data

Integrations do not fail loudly. They fail on a Tuesday and you find out on Thursday when a buyer asks why a discontinued article is still on sale. Most of the questions below are about noticing sooner, and about fixing the source rather than the copy.

The nightly sync says it succeeded, but nothing changed.

The run that succeeds with nothing in it is the failure that hurts most. A source system changed an export path, the feed read an empty file, reported zero records and finished green. Open Integration Studio › Runs, read the record count against previous days, and enable notify on empty result on the workflow so this is never discovered by a buyer again. Monitor for expected activity as well as for errors. See Monitor your syncs.

Where do I look when the ERP did not get an order?

Integration Studio › Runs, sorted by time. If the order's own History tab shows the placement event and nothing after it, the order was placed correctly and the problem is downstream, in a run that failed or never started. An order that is days old with acknowledged_at empty is an integration alarm; build a daily check for it. See Monitor your syncs.

The sync fails with 401 or 403.

The credential was rotated, expired, or the technical account on the other side was disabled, often by a password-rotation policy that did not exclude it. Renew the credential on the connection under Integrations › Credentials, and ask the other side to exempt technical accounts from rotation. A connection refused or a timeout is their maintenance window or your addresses not being allow-listed. See Common sync errors.

Every run creates records and nothing updates.

The identifier format differs: a leading zero, a prefix, or case. Every row looks new, so every row is created. Stop the run rather than letting it finish, because duplicates that carry prices and order lines are a careful manual merge. Normalise the identifier in the mapping, then merge or remove what was already created. See Common sync errors.

Which system should own which field?

Exactly one, per field, written down. Typically the ERP owns the article number, weight, tax class, stock and invoiced prices; the platform owns everything a buyer reads, such as descriptions, images and technical attributes. If the ERP owns a field and someone edits it in the Cockpit, the next sync overwrites it and the edit looks like a bug rather than the rule working. Decide this before you map a single field. See Deciding your system of record.

How do I get alerted when a sync fails?

On the workflow under Integrations › Workflows, enable notify on failure to a group address, not a personal one, notify on empty result, and a staleness alert if no successful run completed within the expected interval. Then send one deliberately failing run through the chain and confirm a human receives the mail. The bell in the Cockpit topbar is a feed, not an alerting system, and has no preferences. See Monitor your syncs.

A webhook never arrives at our system.

In the order that resolves fastest: did the event happen at all, visible in Events › Event Stream; does anything subscribe to that topic, which the event's Routed to section answers; is the destination still enabled, since one that failed persistently is disabled automatically; what do the delivery attempts say, where persistent 4xx is your payload and 5xx is their system; and is the receiver reachable from the public internet at all. See Common API problems.

The webhook signature never matches.

The body was re-serialised, by far the most common cause: the signature covers the raw request bytes exactly as received, and a framework that parses and re-encodes the JSON changes whitespace or key order. Capture the raw body before any parsing. Then check the secret is from the right destination, that the receiver accepts any of several comma-separated signatures during a rotation, and that it compares hexadecimal; base64 never matches. See Set up webhooks.

How do I create an API key for our integrator, and which scopes?

Settings › API Keys › Create API key. Name it for the system, such as erp-order-sync-prod, never for a person. Grant custom scopes in the form resource.action, such as orders.read or inventories.write, and only those; an ERP that pulls orders and never changes them needs orders.read. Do not tick *. The secret appears once; paste it straight into the integrator's secret store, never into email or a ticket. Then test it with one GET before anyone builds against it. See Create an API key.

The key returns 401 immediately after I created it.

The copy, not the key. Long secrets get truncated by chat clients, spreadsheet cells and terminal wrapping. Revoke and reissue rather than debugging; it takes two minutes. The other cause is two credentials sent at once: send either X-Revenexx-Api-Key or Authorization: Bearer, never both. A 403 on some calls and not others is a missing scope, and the message names it. See Common API problems.

We are rate limited constantly.

One-off 429s mean the backoff is working. A steady stream means something is designed wrong: a job that makes one request per article instead of a bulk call, two integrations competing for the same per-tenant limit, or parallel workers retrying in lockstep without jitter. Honour Retry-After, and move the per-article loop to a bulk export. See Rate limits, quotas and fair use.

Is there a punchout screen in the Cockpit?

No. A punchout is assembled from three pieces: a channel of type PunchOut in Configuration › Channels with Unassigned rows set to Hidden until assigned, a credential under Integrations › Credentials, and a connector or workflow that handles the round trip and knows the standard (OCI 4, OCI 5 or cXML), the channel and the customer organization. Order transmission is a separate message from the punchout and is configured separately. See Set up a punchout.

The punchout buyer sees our whole catalog, or list prices.

The channel's unassigned-rows setting was left at Inherit while the tenant default is open, so the channel shows every article and every price. Set it to Hidden until assigned before handing over credentials, then filter the product grid by the channel and count against the contract. List prices mean the customer's conditions are not resolving for that channel; check the contract list's scope. See Set up a punchout.

Can our integrator test without touching live data?

Yes, in a sandbox: a separate tenant with its own keys and its own data, where a failed import costs nothing. Provision it on day one of the integration project, name its keys with the environment so erp-sync in two tenants cannot be confused, and remember that an app not installed on the sandbox answers 404 on paths that exist in production. See The sandbox.