Troubleshooting ServiceNow REST and SOAP Integrations: A Practical Guide

This guide shows how to troubleshoot ServiceNow integrations that use REST or SOAP when connections fail, data stops syncing or records are duplicated. It starts from the observed symptom and checks the cheapest likely causes first, confirming each fix before moving to the next.

Troubleshooting integrations: REST and SOAP

REST and SOAP integrations connect ServiceNow to external systems: data sync, business process integration, reporting. When integrations fail, data does not sync, business processes break, and decisions are made on stale data.

Start from the observed symptom rather than the suspected cause: note exactly what the user or process reported, work through the most probable explanations in order of cheapness to check, and confirm each fix before moving to the next.

Symptom: Integration fails to connect to external system

The integration logs show connection errors: “connection refused”, “timeout”, “host not found”.

Diagnosis: Check network connectivity to the external system (ping, DNS lookup). Check if the external service is running and accepting connections. Check ServiceNow firewall/proxy rules (does ServiceNow have network access to the external system?).

Fix: Verify the target URL is correct (no typos, correct host). Check that the external system is running and listening on the specified port. If behind a firewall, verify firewall rules allow ServiceNow to access the external system. Check proxy configuration in ServiceNow if a proxy is required.

Symptom: Authentication or authorization fails

Logs show “authentication failed”, “invalid credentials”, or “unauthorized access”.

Diagnosis: Check credentials (username, password, API key, certificate). Are credentials correct and still valid? Have credentials expired or been revoked? Check authorization (does the user account have permission to access the resource being requested?).

Fix: Verify credentials are correct. Update if expired (many systems require periodic credential rotation). Check external system logs to see what is being denied and why. May need to update permissions in the external system. Test with a direct API call (curl, Postman) to verify credentials work outside ServiceNow.

Symptom: Data not transferring or partial data transfer

Integration connects and authenticates but data is not syncing or only some data is transferred.

Diagnosis: Check the integration query (what data is supposed to be retrieved). Check if data exists in the source system (does the query return any records?). Check if there are data transformation errors (source data format does not match expected format).

Fix: Verify the query is correct and returns expected data (run the query in the source system directly). Check data mapping (field names, data types) match between systems. If source system returns data but ServiceNow does not receive it, check for format issues (encoding, date formats, special characters).

Symptom: Performance problems or timeouts

Integration runs but is slow or times out before completing.

Diagnosis: Check volume of data being transferred (large data sets cause slow performance). Check external system performance (is the external system responding slowly?). Check integration query (is it efficient or doing unnecessary work?).

Fix: Optimize the integration query (limit date range, filter for necessary records only, reduce number of fields). Increase timeout if the integration legitimately takes time. Batch large transfers (multiple smaller syncs instead of one large sync). Check external system performance (contact the external system admin).

Symptom: Data corruption or incorrect transformation

Data transfers but arrives in ServiceNow with errors: fields are wrong, dates are incorrect, special characters are corrupted.

Diagnosis: Check data mapping (which source field maps to which ServiceNow field, are formats being transformed correctly). Check if the integration handles edge cases (null values, missing fields, special characters).

Fix: Review the mapping specification and test with sample data that includes edge cases. Update mapping if incorrect. May need to add transformation logic (conversion functions, validation) if data arrives in unexpected formats.

Symptom: Integration runs but duplicate records created

Integration creates new records but does not update existing records, causing duplicates.

Diagnosis: Check how the integration identifies existing records (is there a unique key or matching logic?). If no matching logic, the integration creates a new record for every sync instead of updating.

Fix: Implement a unique key or matching logic (match on external ID, email, or other unique field). Configure the integration to update matching records, not just create. Deduplicate existing records if duplicates have already been created.

Symptom: Integrations scheduled but not running

The integration schedule shows it should run but does not execute.

Diagnosis: Check if the integration is enabled. Check the schedule (is the next run date in the future or past?). Check workflow status (is there an error in the integration workflow?).

Fix: Enable the integration if disabled. Verify the schedule date/time (manually trigger to test if the schedule is the issue). Check workflow logs for errors. If a workflow is stuck or in error state, investigate and clear the error.

When to escalate

Escalate to your platform team if: troubleshooting does not resolve the issue, the problem is a system configuration or database issue, external system connectivity is a mystery, or performance is severely degraded. Provide: the symptom, troubleshooting steps taken, logs, and affected records.

Read the status code before reading the payload

When an outbound call fails, the first useful fact is the status the external system returned, or the fact that it returned nothing. The status narrows the search to a small set of causes, and each cause has a different first check. Teams that open the payload first often spend a long time comparing JSON fields that were never the problem.

Working through a failed call in a fixed order

Changing several things at once makes the cause hard to identify. The sequence below keeps each step separate, and it stops as soon as the fault is found.

1. Find the outbound request in the log and record the endpoint, method, status, duration and the time it started.
2. Reproduce the call with the REST message’s test action, using the same credential alias the workflow uses. This tells you whether the fault lives in the message definition or in the script that calls it.
3. Compare the request body in the log with the vendor’s schema for that resource, field by field, including data types and required fields.
4. Send the same request from a tool outside ServiceNow with identical headers. If it succeeds there, the difference is in what ServiceNow sends, not in the vendor.
5. Only then change configuration, and change one thing at a time with a dated note of what was changed and why.

Integrations that route through a MID Server

When the external system sits on a private network, the call leaves ServiceNow through a MID Server rather than going out directly. A failure that looks like a vendor problem may actually sit in the MID Server’s own status, its connection back to the instance, or the proxy settings it uses. Check the MID Server’s status and its log before opening a ticket with the vendor, and confirm which credential the outbound message is attached to using the explanation of connection and credential aliases. Also check the ECC queue for messages stuck in an error or waiting state, because a backlog there can hold up work that appears to have nothing to do with the failing call.

Duplicates and partial updates after a failure

A troubleshooting session is not finished when the call finally succeeds. Retries after a timeout are where duplicate records come from. The vendor may have processed the first request even though ServiceNow never received the reply. Before retrying a create call, search the external system for the record using your correlation identifier. If the vendor offers no lookup, limit automatic retries to calls that set absolute values, such as updates to a named field, and handle creates by hand after checking the other side. Write down which records were touched during the incident so the clean-up does not depend on memory. Recurring patterns of this kind are listed in the common mistakes guide for these integrations.

Deciding when to keep investigating and when to escalate

The aim of escalation is to hand over evidence, not a symptom. Who should receive that evidence, and how quickly, is covered in a discussion of integration monitoring and ownership. A useful escalation carries the endpoint, the status, the duration, one example request and response with identifiers masked, and the steps already taken.

Questions people raise during an incident

Why does the call work in a test tool but fail when a workflow makes it?

Common reasons are a different account running the workflow, a header that the test tool adds automatically, a shorter time limit inside the workflow context, or a variable that resolves to something unexpected at run time. Compare the outgoing request in the log with the one your test tool sent, and the difference is often easy to spot. Questions about which account a call should run as belong with the security and access design guide for these integrations.

Should every response body be logged in full?

No. Full bodies make logs large and can expose personal or credential data. Log the status, the duration and an identifier, and keep full bodies only for a short diagnostic window that is turned off afterwards. Masking rules should be agreed with whoever owns data protection before they are switched on.

How do we tell a slow integration from a broken one?

Compare the current duration with a baseline taken during normal operation. A call that takes much longer than usual but completes is a performance problem. A call that stops completing at all is a fault. Keeping the baseline in a simple table makes the comparison quick during an incident.

Can a retry make an incident worse?

Yes, when the retried call is not safe to repeat. Retries multiply load on a service that is already struggling, and they create duplicates when the original request was accepted. Stop automatic retries during an active vendor incident and resume them only after the call is confirmed to be safe. The wider design of retry and fallback logic is set out in a guide to integration error handling.