Outbound REST Messages let ServiceNow push data to external systems — webhooks, third-party APIs, or other ServiceNow instances. This guide walks you through building one that can authenticate, pass dynamic values, and handle responses properly.
Why REST Messages replace custom HTTP calls
Before REST Messages, developers wrote custom HTTP requests scattered across Business Rules and Script Includes, each handling authentication and error handling differently. This led to duplicated code, inconsistent retry logic, and credentials hardcoded in scripts. Platform admins couldn't see what external calls were being made or troubleshoot integration failures without digging through code. REST Messages centralize outbound HTTP configuration in one place where admins can manage endpoints, authentication, and logging without touching JavaScript.
How REST Messages structure outbound calls
A REST Message is a reusable template that defines the target system, authentication method, and available HTTP operations. You create one REST Message per external system, then add HTTP Methods (GET, POST, PATCH, DELETE) for each operation you need. Each method can have its own endpoint path, headers, and request body template. The key insight: REST Messages separate the configuration (endpoint URLs, auth credentials) from the execution (calling it from scripts with dynamic values). This means you can change endpoints without updating code, and reuse the same authentication across multiple operations.
Production-quality improvements and monitoring
Once your basic REST Message works, add proper error handling in your calling scripts, implement retry logic for transient failures, and use the REST Message log tables for monitoring. Consider creating a wrapper Script Include that standardizes how your team calls REST Messages and handles common response patterns. For high-volume integrations, add rate limiting and circuit breaker patterns. The built-in REST Message test functionality is useful for development, but real monitoring comes from logging actual calls and their responses in your application scripts.
Before you start
- •rest_service_admin role or admin role
- •Network connectivity to the target REST API endpoint
- •Valid credentials for the external system if authentication is required
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 record
Navigate to System Web Services > Outbound > REST Message and click New. Fill in the Name field with something descriptive like 'Slack Notifications' or 'JIRA Integration'. Set the Endpoint to the base URL of the target system (e.g., https://api.slack.com or https://jira.company.com). Don't include specific API paths here — those go in the HTTP Methods. The endpoint should be just the protocol, domain, and any common base path that all your API calls will share.
Configure authentication method
In the Authentication tab, choose your authentication type. For API keys, select 'Basic' and put the key in the User name field (leave Password blank). For OAuth, select 'OAuth 2.0' and configure your client credentials. For bearer tokens, select 'Basic' and put 'Bearer your-token-here' in the User name field. If the API expects custom headers for authentication, leave this blank and add them in the HTTP Method headers instead.
Add an HTTP Method
Click the HTTP Methods tab, then New. Set the Name to describe the operation like 'Create Issue' or 'Send Alert'. Choose the HTTP method (GET, POST, PATCH, DELETE). In the Endpoint field, add the specific API path like '/api/v1/issues' or '/webhooks/abc123'. This gets appended to the base endpoint from step 1. Check 'Lock' to prevent the endpoint from being overridden when called from scripts — you want this checked unless you need dynamic endpoint paths.
Set up request headers and body
In the HTTP Method's HTTP Headers tab, add any required headers like 'Content-Type: application/json' or custom authentication headers. In the Content field, add your request body template. Use ${variable_name} syntax for dynamic values you'll pass from scripts, like '{"title": "${issue_title}", "priority": "${priority_level}"}'. For GET requests, leave Content empty and add query parameters to the endpoint URL using the same ${variable} syntax.
Test the REST Message
Save the HTTP Method, then click 'Test' at the bottom of the form. Fill in values for any variables you defined with ${} syntax. Click 'Send'. Check the Response Status — 200-299 means success, 400+ means there's a problem with your request format or authentication. Review the Response Body to confirm the external system received your data correctly. Fix any authentication or formatting issues before using this in scripts.
The test functionality creates a variable input for every ${variable} it finds in your endpoint URL, headers, and body content.
Call from scripts using RESTMessageV2
In your Business Rule or Script Include, instantiate the REST Message with 'var rm = new sn_ws.RESTMessageV2('Your_REST_Message_Name', 'HTTP_Method_Name');'. Set variables using 'rm.setStringParameterNoEscape('variable_name', value);'. Execute with 'var response = rm.execute();' and check results with 'var statusCode = response.getStatusCode();' and 'var body = response.getBody();'. Always check the status code before processing the response body — don't assume external APIs will always return success.
Best practices
Use setStringParameterNoEscape() instead of setStringParameter() to prevent ServiceNow from URL-encoding JSON request bodies and breaking your API calls.
Always check response.getStatusCode() before processing response.getBody() — external APIs fail in unpredictable ways and error responses often aren't valid JSON.
Set the 'Lock' checkbox on HTTP Methods unless you specifically need to modify endpoints at runtime — unlocked endpoints are a common source of integration bugs.
Create wrapper Script Includes for complex REST Messages so multiple developers can call them consistently without duplicating authentication and error handling logic.
Use descriptive variable names like ${incident_number} instead of ${var1} — you'll thank yourself when debugging failed calls months later.
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