REST Message

What It Is

A REST Message is ServiceNow's configuration template for making outbound HTTP calls to external systems. It stores the endpoint URL, authentication credentials, HTTP methods, headers, and request body templates in a reusable format that scripts can invoke programmatically. Rather than hardcoding API details in business rules or script includes, REST Messages centralize these configurations in a manageable, version-controlled structure. They solve the fundamental problem of maintaining consistent, secure outbound integrations across your ServiceNow instance without scattering connection details throughout your codebase.

REST Messages live in the System Web Services application within ServiceNow's integration layer, specifically in the sys_rest_message table. Each REST Message can contain multiple HTTP Methods (sys_rest_message_fn table), allowing you to define GET, POST, PUT, DELETE operations for the same external service within a single configuration. They integrate directly with ServiceNow's scripting environment through the RESTMessage API and GlideHTTPRequest classes, executing within the same transaction context as the calling script. The platform treats these as first-class integration objects, providing logging, error handling, and security controls specifically designed for outbound API calls.

The underlying execution model relies on ServiceNow's HTTP client infrastructure, which handles connection pooling, SSL certificate validation, proxy routing, and authentication token management. REST Messages inherit the security context of the calling user or system account, applying outbound network ACLs and authentication policies at runtime. They support variable substitution using dollar-sign notation (${variable_name}), allowing dynamic endpoint construction and request body generation based on runtime data. The platform caches authentication tokens when using OAuth or similar protocols, reducing authentication overhead for subsequent calls within the same session.

You cannot function without REST Messages when building production-grade integrations that need to survive upgrades, scope changes, and credential rotations. Hardcoded API calls in scripts become maintenance nightmares when endpoints change, authentication expires, or you need to replicate the same integration pattern across multiple environments. REST Messages become essential when you're synchronizing data with external systems like Active Directory, Salesforce, or custom applications, sending notifications to Slack or Teams, or integrating with ITSM tools for ticket escalation. They're also required for any integration that needs to pass ServiceNow's security reviews, as they provide proper credential storage, audit trails, and access controls that embedded API calls cannot match.

Platform administrators typically create and configure REST Messages, setting up the base endpoints, authentication, and security policies. Developers consume these configurations in their scripts, using the predefined HTTP methods to make actual API calls without needing to understand the underlying authentication or connection details. Integration specialists often serve as the bridge between these roles, defining the technical requirements and testing patterns that administrators implement. This separation of concerns allows credential management to remain centralized while enabling developers to focus on business logic rather than connection mechanics.

Recent ServiceNow releases have enhanced REST Message capabilities with improved OAuth 2.0 flows, better error handling for timeout scenarios, and enhanced logging through the sys_rest_message_log table. Vancouver introduced more granular control over SSL certificate validation and expanded support for custom authentication headers. Xanadu added integration with the Credential Store for more secure authentication token management and improved the variable substitution engine to handle complex JSON payloads more reliably. These changes have made REST Messages more suitable for enterprise-grade integrations while maintaining backward compatibility with existing configurations.

Where to Find and Configure It

Navigate to System Web Services > Outbound > REST Message to create and manage REST Message configurations. This is where you define endpoints, authentication methods, and default headers for your outbound integrations.

Access REST Messages in Studio via Create Application File > Integration > REST Message to build them as part of your scoped application development. In App Engine Studio, find them under Logic and automation > Integrations where you can configure outbound API calls through the guided interface.

Monitor REST Message execution logs at System Logs > REST Messages to troubleshoot failed calls and review request/response details. View the underlying data in the sys_rest_message.list table to see all configured REST Messages across your instance. HTTP Methods for each REST Message are stored in sys_rest_message_fn.list where you can examine the specific configurations for GET, POST, PUT, and DELETE operations.

How It Works Step by Step

REST Messages operate as templates that get instantiated and executed when called from ServiceNow scripts. The REST Message configuration provides the static elements—endpoint URL, authentication method, default headers—while the calling script provides dynamic elements like variable substitutions, request body data, and runtime parameters. ServiceNow's HTTP client infrastructure handles the actual network communication, applying security policies, proxy settings, and connection pooling automatically.

The platform evaluates variable substitutions using the format ${variable_name} at runtime, replacing these placeholders with values from the calling script's parameter map. Authentication credentials get resolved from the configured authentication profile, which may involve retrieving stored passwords, generating OAuth tokens, or building authentication headers. The system applies outbound network ACLs and security policies before making the actual HTTP request, ensuring that only authorized calls reach external endpoints.

The Execution Order

1. Script instantiates REST Message using new sn_ws.RESTMessageV2('message_name', 'http_method') or GlideHTTPRequest
2. ServiceNow loads REST Message configuration from sys_rest_message and specific HTTP Method from sys_rest_message_fn
3. System resolves authentication credentials from configured authentication profile or credential store
4. Script sets variable substitutions via setStringParameterNoEscape() or setRequestBody()
5. Platform performs variable substitution in endpoint URL, headers, and request body
6. System applies outbound network ACLs and validates SSL certificates if required
7. HTTP request executes through ServiceNow's HTTP client with configured timeout and retry settings
8. Response gets logged to sys_rest_message_log table and returned to calling script as HTTPResponse object

// Instantiate the REST Message
var restMessage = new sn_ws.RESTMessageV2('External System API', 'POST User');

// Set variable substitutions
restMessage.setStringParameterNoEscape('user_id', current.sys_id);
restMessage.setStringParameterNoEscape('environment', gs.getProperty('instance.name'));

// Build request body
var requestBody = {
    name: current.name.toString(),
    email: current.email.toString(),
    department: current.department.getDisplayValue()
};
restMessage.setRequestBody(JSON.stringify(requestBody));

// Execute the call
var response = restMessage.execute();
var responseBody = response.getBody();
var statusCode = response.getStatusCode();

// Handle response
if (statusCode == 200 || statusCode == 201) {
    gs.info('User created successfully: ' + responseBody);
} else {
    gs.error('API call failed with status: ' + statusCode + ', Response: ' + responseBody);
}

Real-World Scenarios

Synchronizing Active Directory User Updates

Your organization needs to update Active Directory attributes when ServiceNow user records change, specifically pushing department and manager changes back to AD immediately. This prevents the nightly LDAP sync from overwriting ServiceNow changes with stale directory data.

Create a REST Message named Active Directory API with endpoint https://your-ad-api.company.com/users/${user_id}. Configure basic authentication using a service account stored in the credential store. Add an HTTP Method called Update User with method PATCH and content type application/json. Create a business rule on the sys_user table that triggers after update when department or manager fields change, instantiating the REST Message and setting the user's employee ID as the user_id parameter.

Watch for authentication token expiration—Active Directory APIs often use short-lived tokens that need refresh handling in your business rule. Set the REST Message timeout to 30 seconds maximum since AD operations should be fast, and implement error handling that doesn't block user updates if the AD API is unavailable. Consider using the async business rule option to prevent AD API latency from slowing down ServiceNow user interface operations.

Escalating Critical Incidents to External Paging System

High-priority incidents need immediate notification through PagerDuty or similar alerting platforms when they're created or escalated to Priority 1. The integration must pass incident details, assignment group information, and create actionable alerts that responders can acknowledge directly from their mobile devices.

Configure a REST Message named PagerDuty Integration pointing to https://events.pagerduty.com/v2/enqueue with API key authentication stored in a credential record. Create an HTTP Method Create Alert using POST method with a request body template that includes ${incident_number}, ${short_description}, and ${assignment_group} variables. Build a business rule on the incident table that fires when priority equals 1 - Critical and state is New or In Progress.

Test the integration thoroughly with non-production PagerDuty services to avoid alert fatigue during development. PagerDuty's API rate limiting can cause failures during incident storms, so implement exponential backoff retry logic in your business rule. Store the PagerDuty incident key in a custom field on your ServiceNow incident record to enable bi-directional updates and prevent duplicate alerts when the same incident gets updated multiple times.

Validating Configuration Items Against External CMDB

Your ServiceNow CMDB needs real-time validation against an authoritative external system like AWS Config or Azure Resource Manager to ensure CI accuracy. Before allowing CI updates or new CI creation, the system should verify that the configuration item actually exists in the external system with matching attributes.

Set up a REST Message called AWS Config Validation with endpoint https://config.${aws_region}.amazonaws.com using AWS signature version 4 authentication through a credential store entry. Create an HTTP Method Get Resource with GET method and query parameters for resourceType and resourceId using variable substitution. Implement a script include that other CI business rules can call, passing the CI's external ID and resource type to validate against AWS Config. Use this validation in before business rules on CI tables to prevent invalid CI creation or updates.

AWS authentication signatures expire quickly and are sensitive to clock skew between ServiceNow and AWS servers. Monitor the REST Message logs for authentication failures and ensure your ServiceNow instance time synchronization is properly configured. Consider implementing a circuit breaker pattern that disables external validation temporarily if AWS Config becomes unavailable, allowing CI operations to continue during outages while logging the bypass for later reconciliation.

The Classic Mistake

// BAD: Hardcoded credentials in HTTP Headers tab
// Header Name: Authorization
// Header Value: Bearer abc123-hardcoded-token

var request = new sn_ws.RESTMessageV2('MyExternalAPI', 'GET');
request.setStringParameter('sys_id', current.sys_id);
var response = request.execute();
var responseBody = response.getBody();
var status = response.getStatusCode();

if (status != 200) {
    gs.error('API call failed: ' + responseBody);
}

// Token gets exposed in logs, update sets, and database
// No rotation capability, credentials visible to anyone with admin access

This approach fails because the hardcoded credentials get stored in plain text in the sys_rest_message table and appear in every update set containing the REST Message. ServiceNow logs the complete header values in System Log > REST, exposing sensitive credentials to anyone with log access. When tokens expire or need rotation, you must manually hunt down every REST Message using those credentials across all instances.

// GOOD: Using Authentication Profile
// REST Message > Authentication tab: 
// Type: OAuth 2.0
// Authentication Profile: MyAPI_OAuth_Profile

var request = new sn_ws.RESTMessageV2('MyExternalAPI', 'GET');
request.setStringParameter('sys_id', current.sys_id);

// Authentication handled automatically via profile
// Token refresh managed by platform
// Credentials encrypted and centrally managed
var response = request.execute();
var responseBody = response.getBody();
var status = response.getStatusCode();

if (status != 200) {
    gs.error('API call failed: ' + responseBody);
}

When to Use This vs Alternatives

REST Messages are the correct choice when you need reusable, configurable outbound HTTP calls that can be shared across multiple scripts and business rules. They excel when you need parameter substitution, authentication profiles, and the ability to modify endpoints without code changes.

Choose REST Messages When

Multiple scripts need to call the same external API with different parameters, or when non-developers need to modify endpoints and authentication without touching code. REST Messages provide the template approach that GlideHTTPRequest cannot match. Use them when you need OAuth 2.0 token management, complex authentication flows, or when the integration spans multiple applications within ServiceNow.

Use GlideHTTPRequest Instead When

You need a simple, one-off HTTP call with complete programmatic control over headers, body, and error handling within a single script. GlideHTTPRequest is faster to implement when authentication is basic (API key in header) and the endpoint won't change. Choose this for internal ServiceNow-to-ServiceNow calls or when you need precise control over timeout handling and retry logic.

Use Both Together When

You have a complex integration requiring both standardized calls (via REST Messages for common operations) and dynamic calls (via GlideHTTPRequest for edge cases). This pattern works well for ERP integrations where you need standard CRUD operations through REST Messages but custom queries through direct HTTP calls. The REST Message handles authentication and base configuration while GlideHTTPRequest provides flexibility for complex scenarios.

Platform Interactions & Side Effects

• Creates records in sys_rest_message and sys_rest_message_functions tables, with HTTP methods stored as separate function records
• All REST Message executions log to System Log > REST including full request/response bodies when debug logging enabled
• Business Rules and Script Includes calling REST Messages inherit the execution user's session timeout and security context
• Update Sets capture REST Message changes but not Authentication Profile credentials, breaking deployments across instances
• OAuth 2.0 authentication profiles cache tokens in oauth_credential_cache table, with automatic refresh 5 minutes before expiration
• Failed REST Message calls in Business Rules can cause transaction rollbacks, preventing record saves even when the external call isn't critical
• MID Server property mid.ssl.use_internal_keystore affects REST Message SSL certificate validation when using MID Server execution
• System property glide.rest.outbound.timeout sets global timeout (default 30 seconds) but individual REST Messages can override this
• REST Message parameter substitution uses ${parameter_name} syntax, which conflicts with Workflow variable notation and requires escaping
• ACLs on sys_rest_message table don't prevent script execution of REST Messages, only UI access to configuration

Debugging and Troubleshooting

Most REST Message failures manifest as silent failures in Business Rules or Script Includes, with scripts continuing execution but external systems never receiving expected data. Users report that integrations "stopped working" without error messages, while admins see generic "Connection refused" or "401 Unauthorized" responses. The most insidious failures occur when authentication tokens expire mid-process, causing intermittent failures that correlate with token refresh cycles.

Start debugging in System Log > REST which captures every outbound call with timestamps, response codes, and full payloads when glide.rest.debug property is enabled. Authentication failures appear in System Log > All with source com.glide.security.oauth, while SSL certificate issues show as javax.net.ssl.SSLHandshakeException errors.

Look for error messages like "REST Message function not found" when parameter names don't match, "Authentication profile not found" when OAuth profiles are missing across instances, and "Connection timeout" when glide.rest.outbound.timeout is too aggressive. Token refresh failures generate "invalid_grant" OAuth errors in logs exactly 5 minutes before the original token expiration time. Parameter substitution failures result in literal ${parameter_name} strings appearing in request URLs or bodies, visible in the REST debug logs.

Diagnostic Checklist:

• Enable glide.rest.debug=true and check System Log > REST for complete request/response details
• Test REST Message using Test link in REST Message form to isolate configuration issues from script problems
• Verify Authentication Profile exists in target instance and credentials are current
• Check oauth_credential_cache table for token expiration times and refresh failures
• Validate parameter names in setStringParameter() calls match HTTP method configuration exactly
• Confirm MID Server connectivity if using Use MID Server option, check MID Server logs for SSL/firewall issues
• Review Business Rule execution order if REST Message calls fail in async rules or cause transaction rollbacks

Quick Reference

• REST Message parameter names are case-sensitive and must match exactly between setStringParameter() calls and HTTP method variable definitions
• OAuth 2.0 tokens refresh automatically 5 minutes before expiration, but failed refresh attempts don't retry until the next REST Message execution
• Maximum request body size is 10MB by default, controlled by glide.rest.max_request_size system property
• Authentication Profiles don't migrate with Update Sets - they must be manually recreated in each instance with environment-specific credentials
• HTTP method names in REST Messages can't contain spaces or special characters - use underscores for multi-word method names
• REST Message functions inherit the calling script's transaction scope - failures in synchronous Business Rules cause record save rollbacks
• Variable substitution in HTTP headers supports only string parameters - complex objects must be serialized before parameter assignment
• MID Server execution adds approximately 2-3 seconds latency compared to direct ServiceNow instance execution
• REST debug logging captures sensitive data in plain text - disable glide.rest.debug in production environments after troubleshooting
• REST Message timeout values must be integers in milliseconds - decimal values cause silent failures with default 30-second timeout applied