ServiceNow needs to talk to external systems — triggering notifications in Slack, updating records in your CMDB, or calling third-party APIs when something changes. This guide shows you how to make outbound REST calls from your server-side scripts and handle the responses properly.
Why outbound REST calls matter
Before outbound REST integration, teams were stuck with manual processes every time ServiceNow needed to notify or update external systems. Someone would export data, manually update the other system, then come back to update ServiceNow. Platform admins and developers needed a way to trigger these external actions automatically — when an incident gets resolved, when a user gets onboarded, when a change request gets approved. The alternative is either manual work or building custom middleware just to connect two systems.
How REST message execution works
ServiceNow's sn_ws.RESTMessageV2 API lets you make HTTP calls from server-side JavaScript. You instantiate a REST message object, set parameters and headers, execute the call, then parse the response. The key choice is synchronous versus asynchronous execution. Synchronous calls block the current transaction until the external system responds — fine for fast APIs, terrible for slow ones or when called from Business Rules that users are waiting on. Asynchronous calls return immediately and process the response in the background.
Production-quality REST integration
Once your basic REST call works, production improvements include: robust error handling that checks both network failures and application-level errors, response parsing that handles unexpected JSON structures gracefully, and retry logic for transient failures. Consider moving slow or unreliable calls to scheduled jobs instead of real-time Business Rules. Add logging that captures both request and response details so you can debug integration failures weeks later.
Before you start
- •admin role or rest_service role
- •Target system endpoint URL and authentication credentials
Sourdough: ServiceNow Monitoring and Analytics
A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.
Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.
Step by step
Create the REST message object
In your server-side script (Business Rule, Script Include, or Flow script step), instantiate the REST message using sn_ws.RESTMessageV2(). Pass the target system's base URL as the first parameter, or the method name if you're using a predefined REST message from System Web Services > Outbound > REST Message. Store this in a variable since you'll chain method calls on it.
Use predefined REST messages for production integrations — they're easier to maintain and can store authentication credentials securely.
Set the HTTP method and endpoint
Call setHttpMethod() to specify GET, POST, PUT, PATCH, or DELETE. Then call setEndpoint() with the full URL if you instantiated with a base URL, or the specific path if you're extending a predefined message's base URL. For REST APIs, this is typically something like '/api/v1/users' or '/incidents'.
Configure authentication and headers
Call setBasicAuth(), setBearerAuth(), or setRequestHeader() to authenticate with the target system. Most modern APIs use Bearer tokens or API keys passed in headers. Use setRequestHeader('Content-Type', 'application/json') for POST and PUT requests that send JSON data. Add any other required headers like User-Agent or custom API versioning headers.
Set request parameters and body
For query parameters, call setQueryParameter(name, value) for each parameter. For POST/PUT requests with JSON bodies, call setRequestBody() with a JSON string — use JSON.stringify() to convert JavaScript objects. Don't mix query parameters with request body data unless the API specifically requires both.
Use setStringParameterNoEscape() instead of setQueryParameter() when the parameter value contains special characters that shouldn't be URL-encoded.
Execute the REST call
Call execute() for synchronous execution or executeAsync() for asynchronous. Synchronous returns a response object immediately but blocks the current transaction. Asynchronous returns null immediately and processes in background — you can't access the response in the same script. Wrap the execute() call in a try/catch block to handle network failures.
Parse response and handle errors
Check response.getStatusCode() first — 200-299 indicates success, anything else is an error. Use response.getBody() to get the response text, then JSON.parse() if it's JSON data. Check for both HTTP errors (status code) and application errors (error fields in the JSON response). Log both the request details and response for debugging.
Many APIs return 200 status but include error details in the JSON — always check both status code and response body structure.
Handle Business Rule timing considerations
If calling from a Business Rule, use 'async' timing to avoid blocking the user's transaction. Synchronous REST calls in 'before' or 'after' Business Rules make users wait for the external system to respond. For critical integrations where you need the response before proceeding, consider using a different trigger mechanism like scheduled jobs or manual user actions.
Best practices
Never make synchronous REST calls from Business Rules that users trigger — external system delays will make your ServiceNow instance feel slow.
Always check both response.getStatusCode() and parse the response body for application-level errors — many APIs return 200 with error details in JSON.
Set reasonable timeouts using setHttpTimeout() to prevent scripts from hanging when external systems are down.
Log both outbound request details and response data — you'll need this information to debug integration failures later.
Use predefined REST messages instead of hardcoding URLs and credentials in scripts — it's more secure and easier to maintain across instances.
Test Your Knowledge
Quick 3-question quiz — see how your ServiceNow skills stack up.
A list view on a table with millions of records is slow. Best fix?
Select an answer to continue