What Is ServiceNow REST and SOAP Integrations? A Plain-Language Guide

REST vs. SOAP: Basic Definitions

REST (Representational State Transfer) and SOAP (Simple Object Access Protocol) are two approaches to integrating systems. Both allow one system to request data from another system over the network. The main difference: REST is lightweight and easy to use; SOAP is more formal and feature-rich.

REST uses HTTP verbs (GET, POST, PUT, DELETE) to represent actions. A GET request fetches data; a POST request creates new data; a PUT request updates data; a DELETE request removes data. SOAP uses XML messages wrapped in HTTP. The message structure is more complex but also more standardised.

When to Use REST

Use REST for most integration scenarios. REST integrations are simple to build, easy to test, and widely supported. Almost every modern system has a REST API. REST is the de facto standard for cloud services, mobile apps, and web applications.

ServiceNow recommends REST for new integrations. REST is faster to develop and easier to troubleshoot than SOAP.

When to Use SOAP

SOAP is older but still relevant for systems that primarily expose SOAP APIs (some enterprise systems, legacy systems). If the system you are integrating with only has a SOAP API, you may need to use SOAP. SOAP also offers features like built-in transaction support and standardised error handling that REST does not provide.

However, even when the target system has SOAP, you can often wrap it with REST or use an intermediary tool. Most teams prefer to avoid SOAP if possible due to its complexity.

How REST Integrations Work in ServiceNow

A REST integration in ServiceNow involves: defining a REST API call (which system, which endpoint, which data to send), triggering the call (on record create, on scheduled interval, on manual button click), and handling the response (storing returned data, error handling).

ServiceNow provides outbound REST Messages, callable from scripts, and the REST step in Flow Designer actions through IntegrationHub, to make REST calls. You define the endpoint URL, HTTP method, headers, and payload. ServiceNow sends the request and receives the response. You can parse the response and use it in your workflow.

How SOAP Integrations Work

SOAP integrations are more complex. You define the SOAP web service (endpoint, method, parameters), and ServiceNow constructs a SOAP message with the required XML structure. The web service processes the request and returns a SOAP response. ServiceNow parses the response and uses the data.

SOAP requires understanding the service’s WSDL (Web Services Description Language), which describes the available methods and required parameters. This adds a step of learning the service’s API structure before building the integration.

Authentication for REST and SOAP

REST integrations typically use OAuth, API keys, or basic authentication. You provide credentials once during setup, and ServiceNow uses them for all requests. OAuth is most secure; it involves a token exchange rather than sharing passwords.

SOAP integrations use similar authentication methods, often basic authentication (username and password). Some SOAP services use WS-Security, a SOAP-specific authentication standard that is more secure but more complex to configure.

Error Handling and Retries

REST and SOAP integrations should handle errors: network timeouts, service unavailability, invalid responses. ServiceNow’s workflow engine supports retry logic: if a request fails, retry after N seconds, and escalate if retries are exhausted.

Define error handling: if the integration fails, should the workflow continue, should it create an incident, should it queue the request for manual retry?

Testing and Debugging Integrations

Test integrations in a staging environment before production. Tools like Postman (for REST) or SoapUI (for SOAP) enable testing API calls outside of ServiceNow. This helps verify that the API works as expected before integrating it into ServiceNow workflows.

If an integration fails in production, enable debug logging in ServiceNow to see request and response details. This helps pinpoint whether the issue is in ServiceNow, in the network, or in the target system.

Performance Considerations

REST and SOAP calls add latency to workflows: waiting for the remote system to respond. If a workflow makes many REST calls, performance can degrade. Consider batching calls (make one call that returns multiple records instead of many calls for individual records) and caching responses (store frequently-accessed data locally to avoid repeated calls).

Monitor integration performance: measure how long REST/SOAP calls take and alert if latency increases (indicating a problem with the target system or network).

Decide the direction and the timing before the protocol

Much of the expensive confusion about these integrations comes from picking the protocol first. The more useful starting point is two questions: which system starts the conversation, and does anyone wait for the answer. Those two answers narrow the ServiceNow mechanism long before anyone argues about REST against SOAP, and the protocol then becomes a detail of the chosen mechanism rather than a strategic choice.

Inbound and outbound are different problems

Teams often describe an integration as one thing when it is really two. The outbound side has to hold credentials, handle the vendor’s throttling and cope with replies that arrive late or not at all. The inbound side has to authenticate callers, decide who may read or change which records, and survive a flood of requests without corrupting data. A design that handles one side well and treats the other as an afterthought often fails in production, and the failure appears on the side that was not designed.

Access on the inbound side should be specified before the endpoint is built, and practical look at REST integration design covers the questions to answer before a REST integration is designed. The user the external system authenticates as needs a narrow role, and the Web service access only setting on that user should be reviewed as part of the design rather than left to whoever created the account.

What a SOAP description tells you and what it does not

A WSDL document describes the operations, parameters and types a SOAP service accepts. It is a useful starting point for building against that service. It does not describe the business rules behind an operation, the rate limits the vendor applies, or the records that will be affected when an operation runs. Read the description for shape, then ask the vendor for the behavior, a question that the acceptance checklist for these integrations will need answered anyway: what a call does to existing data, whether repeated calls are safe, and what error the service returns when a record is locked.

A short procedure for scoping a connection request

1. Name the system that starts each exchange and the system that holds the authoritative version of each field.
2. Decide, for each exchange, whether anyone waits for the reply, and set the maximum acceptable wait in plain terms.
3. Choose the mechanism from the table above, and check that the chosen mechanism supports the authentication the vendor offers.
4. Write down what happens to the work when the exchange fails, including who sees the failure and how it is retried or resolved.
5. Confirm the vendor’s limits on volume and concurrency in writing before the build is estimated.

What the mechanism choice leaves open

Choosing the mechanism does not choose the data design. Which fields exist, how they are named and how records match across the two systems is a separate question, and the integration patterns guide is a better place to work through it. Nor does it decide whether the integration is the right answer at all. Some requirements are better met by a scheduled extract that someone reviews, and that choice is often cheaper, and simpler to defend to an auditor, than a live link.

Questions people ask when they first scope one

Can we use REST for one part and SOAP for another in the same integration?

Yes, and it often happens when a vendor exposes only some of its functions over SOAP. Keep the two parts separate in design and monitoring, so a failure in one does not hide in the other’s logs.

Do we need a middleware product between ServiceNow and the external system?

Not always. A direct connection is simpler to monitor when there are only a few endpoints. An intermediary becomes worth considering when several systems need the same transformation, or when the external side changes often and it is cheaper to absorb those changes in one place.

What does an integration owner need to know that a developer may not?

The owner needs the business meaning of each exchange, who depends on the result, what the acceptable delay is and who gets called when it breaks. Developers can build the mechanism without that knowledge; they cannot decide when the mechanism is failing in a way that matters.

Is it safe to store vendor credentials directly in a script?

It is poor practice, because the credential then lives in code that many people can read and that is hard to rotate. Credentials should sit in a credential alias or a protected store that the message refers to by name, so rotation does not require editing scripts.