Monitor your integrations
Integrations do not fail loudly. They fail at 02:00, in a job nobody watches, and the first symptom is a buyer asking why the price on the invoice is not the price on the screen. Five minutes a day prevents almost all of that.
The four logs
Each answers a different question. Knowing which one to open saves most of the time you would otherwise spend investigating.
| Log | Where | Answers |
|---|---|---|
| Event stream | Events › Event Stream | Did the event happen at all? |
| Delivery attempts | Webhooks › Outbound, on a destination | Did it reach the receiver? |
| Runs | Integration Studio | Did the scheduled job run, and what did it do? |
| Audit log | Integration Studio | Who changed the integration configuration, and when? |
Read them in that order when something is wrong. "The ERP did not get the order" splits immediately into three very different problems depending on which log the trail stops at.
The event stream
Every event your tenant produced, independent of whether any webhook delivered it. Rows show the Event ID, the Topic and when it was Received. Open one and you get the Data, the Metadata, whether it is Retryable, and — the useful part — Routed to: which destinations subscribe to that topic.
That last field answers the most common false alarm in this area. If it says no destination subscribes to the topic, the event fired correctly and nobody asked to hear about it. That is a subscription problem, not a delivery problem.
Watch the volume, too. An event count that jumps tenfold usually means a bulk operation fired per-record events — a bulk edit across 30,000 products, for instance. Worth knowing before your integrator's server finds out.
Delivery attempts
On a webhook destination: the Event, the attempt number (Try), the Status, the HTTP code and When.
How to read it:
| Pattern | Means |
|---|---|
| Everything succeeds on try 1 | Healthy |
| Regular retries that then succeed | The receiver is slow or restarting. It will fail on your busiest day |
Persistent 4xx | Your payload, topic or credentials are wrong |
Persistent 5xx | Their system is broken |
| Successful but slow | A warning, not a success. Rising latency precedes timeouts |
| Nothing at all | The subscription, not the delivery. Check the event stream |
A destination that keeps failing is eventually disabled automatically, so that a dead endpoint does not accumulate an unbounded backlog. Re-enable it from the same screen once the receiver is fixed — and then check what was missed, because re-enabling does not replay history.
Runs
Scheduled workflows and file jobs. What matters here is not only "failed" but succeeded with rejects: a price import that loaded 38,000 rows and rejected 2,000 reports success and has left your catalog partly wrong. Read the row counts, not the status badge. See Monitor your syncs.
The three alerts worth setting
Route all of them to a team address, never a person's mailbox. The whole point is that they still work when somebody is on holiday.
1. A run failed. The obvious one, and the one everybody sets.
2. A run succeeded but rejected rows. The dangerous one. Silent partial success is how a catalog ends up half-updated with nothing in red anywhere.
3. Nothing arrived by the expected time. The one everybody forgets, and the one that catches the worst failure. If the ERP job that produces the nightly file dies, no import fails — nothing happens at all. Every log is clean, every dashboard is green, and your shop serves last week's prices until a customer notices.
That third alarm has to be built as a positive expectation: by 03:00 there should be a completed run of profile X. Absence is the condition.
Key usage
Twice a year, open Settings › API Keys and read the list as an inventory rather than as a screen:
| Question | If the answer is bad |
|---|---|
| Do we know what each key is for? | Revoke it. A key nobody can explain is a key nobody controls |
| Does the scope still match the job? | Narrow it. Scopes get widened during troubleshooting and never narrowed after |
| Is anything still using it? | An unused key is either dead or about to surprise someone |
Does anything hold *? | Replace it with the scopes it actually uses |
| Has anyone left the project? | Revoke their sandbox keys |
Pair that with your own key inventory — key name, integration, owner, who to call when it is revoked — and the review takes twenty minutes instead of a morning.
Correlating a problem
When your integrator says "the API was returning errors on Tuesday", one field turns that into something answerable.
Every response carries an X-Request-ID. If they log it, a specific failing
call can be traced. If they do not, you are comparing timestamps across two
systems with different clocks.
Make it a requirement at go-live: log X-Request-ID on every call, and quote it
in every support case. It is the single cheapest thing in this whole area.
What "healthy" looks like
A useful baseline, so you can recognise the abnormal:
- Error rate steady and low. What matters is the shape of it — a jump from 0.1% to 3% matters even though 3% sounds small.
429responses: rare or none. A steady trickle means an integration is living against the limit and will tip over on your busiest day. See Rate limits, quotas and fair use.- Webhook first-attempt success near 100%.
- Failed queue empty. If it is not, somebody has to decide whether to replay, and that decision has a deadline attached.
- Latency stable. Rising latency is the leading indicator for everything else.
The daily five minutes
- Any failed runs since yesterday?
- Any run that succeeded with rejects?
- Is the webhook failed queue empty?
- Did the expected nightly files all arrive?
- Any
429in the last 24 hours?
Five questions, one person, before the first coffee. Everything on this page exists to make those five answerable in five minutes.
Next
- Common API problems — reading the failures this surfaces.
- Handling API changes — the failures that are scheduled in advance.