AWS Builder Center

ServiceNow ↔ AWS DevOps Agent: A Complete Bidirectional Integration Guide

End-to-end setup guide for bidirectional ServiceNow ↔ AWS DevOps Agent integration, including the critical OAuth auth scope fixes that prevent silent write-back failures.

Introduction

AWS DevOps Agent can automatically investigate operational issues triggered from ServiceNow incidents — and post findings back as incident comments in real-time. This creates a powerful closed-loop: your on-call team creates an incident in ServiceNow, DevOps Agent investigates across your AWS infrastructure, and findings appear directly in the incident timeline without anyone switching tools.
The  official AWS documentation  covers the basics, but during implementation I discovered several critical configuration gaps that cause silent failures — the integration appears to work (no errors anywhere) but findings never post back to ServiceNow. This guide documents the complete end-to-end setup including those fixes.

What You'll Accomplish

  • ServiceNow incidents automatically trigger DevOps Agent investigations
  • DevOps Agent posts investigation findings back to ServiceNow incident comments in real-time
  • Complete audit trail in ServiceNow — no context switching required

Who This Is For

TAMs, Solutions Architects, and DevOps engineers implementing ServiceNow integration with AWS DevOps Agent. Assumes familiarity with ServiceNow administration and AWS console.



Architecture

┌─────────────────────────────────────────────────────────────────────┐
│ BIDIRECTIONAL FLOW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ServiceNow Incident Created │
│ ↓ Business Rule fires (After Insert) │
│ ↓ HMAC-SHA256 signed POST with timestamp │
│ AWS DevOps Agent Webhook │
│ ↓ Investigation starts automatically │
│ ↓ Posts findings to ServiceNow via OAuth (Table API PATCH) │
│ ServiceNow Incident Updated │
│ (comments with findings, root cause, observations) │
│ │
└─────────────────────────────────────────────────────────────────────┘

Key Integration Points

Component
Role
ServiceNow Business Rule
Fires on incident creation, sends signed webhook to AWS
HMAC-SHA256 Signature
Authenticates the webhook payload
AWS DevOps Agent Webhook
Receives incident data, triggers investigation
ServiceNow OAuth (Client Credentials)
Authenticates DevOps Agent write-back to ServiceNow
ServiceNow Table API
Endpoint for posting findings as incident comments



Prerequisites

  • AWS DevOps Agent Space created in us-east-1
  • ServiceNow developer instance with admin access
  • Appropriate IAM permissions for DevOps Agent
  •  curl  command-line tool (Mac/Linux built-in; Git Bash on Windows)
  • A terminal to run REST API commands

Placeholder Reference

Throughout this guide, replace these placeholders with your actual values:
Placeholder
Replace With
Example
 PASSWORD 
Your ServiceNow admin password
 MyP@ssw0rd 
 <your-instance> 
Your ServiceNow instance ID (from URL)
 dev000000 
 admin 
Your ServiceNow admin username
 admin 
Finding your instance ID: If your URL is  https://dev000000.service-now.com , your instance ID is  dev000000 .

Understanding sys_id

ServiceNow uses  sys_id  as a unique identifier for every record (32-character hex string). When you run curl commands, the JSON response contains  sys_id  values — copy them for use in subsequent steps.

Navigating ServiceNow

Many tables referenced in this guide are "hidden" — they won't appear in the filter navigator dropdown. Type the full table name and press Enter — it navigates directly.
Alternative: Use the URL pattern:  https://<your-instance>.service-now.com/now/nav/ui/classic/params/target/<table-name>.list 



Part 1: Configure ServiceNow OAuth

Step 1: Enable OAuth Client Credentials Grant

  1. Navigate to  sys_properties.list  (type in filter navigator → press Enter)
  1. Click New
  1. Fill in:
  • Name:  glide.oauth.inbound.client.credential.grant_type.enabled 
  • Value:  true 
  • Type:  true | false 
  1. Click Submit
Verify: Search for "glide.oauth" in the properties list — confirm Value =  true .

Step 2: Create OAuth Application

  1. Navigate to System OAuth → Inbound Integrations
  1. Click New → Select OAuth - Client Credentials Grant
  1. Fill in:
  • Name:  aws-devops-agent 
  • OAuth application user: Search for and select  System Administrator  (must be admin — lesser roles cause API access issues)
  1. Click Submit
  1. ⚠️ CRITICAL: Immediately copy and save the Client ID and Client Secret (click the lock icon to reveal). You won't see the secret again after leaving this page.

Step 3: Configure Auth Scope (CRITICAL for Write-Back)

This is the most important step. Without proper auth scope configuration, DevOps Agent authenticates successfully but cannot write findings back to incidents. No error messages appear — write-back simply doesn't happen.
This requires configuring 5 ServiceNow tables. Steps 3a-3b can use UI or REST API. Steps 3c-3e must use REST API due to ServiceNow UI limitations.

3a: Create Auth Scope

curl -s -u 'admin:PASSWORD' -X POST \
"https://<your-instance>.service-now.com/api/now/table/sys_auth_scope" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"name": "devopsagent"}'
Save the  sys_id  from the response — needed in subsequent steps.
UI alternative: Navigate to  sys_auth_scope.list  → New → Name:  devopsagent  → Submit.

3b: Map Auth Scope to Table API

Replace  AUTH_SCOPE_SYS_ID  with the sys_id from step 3a:
curl -s -u 'admin:PASSWORD' -X POST \
"https://<your-instance>.service-now.com/api/now/table/sys_api_access_scope" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{
"auth_scope": "AUTH_SCOPE_SYS_ID",
"api": "Table API",
"api_path": "now/table",
"apply_all_resources": "true",
"apply_all_methods": "true",
"apply_all_versions": "true",
"active": "true"
}'
UI alternative: Navigate to  sys_api_access_scope.list  → New → fill in Auth Scope (search for  devopsagent ), REST API ( Table API ), REST API PATH ( now/table ), check all "Apply" boxes → Submit.

3c: Map Auth Scope to OAuth Entity

First, get your OAuth entity's sys_id:
curl -s -u 'admin:PASSWORD' \
"https://<your-instance>.service-now.com/api/now/table/oauth_entity?sysparm_query=name=aws-devops-agent&sysparm_fields=sys_id,name" \
-H "Accept: application/json"
Then create the mapping (replace both  OAUTH_ENTITY_SYS_ID  and  AUTH_SCOPE_SYS_ID ):
curl -s -u 'admin:PASSWORD' -X POST \
"https://<your-instance>.service-now.com/api/now/table/oauth_entity_auth_scope_mapping" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"oauth_entity": "OAUTH_ENTITY_SYS_ID", "auth_scope": "AUTH_SCOPE_SYS_ID"}'
Why REST API? The UI ( oauth_entity_auth_scope_mapping.list ) has dropdown filters that may not show your OAuth entity.

3d: Create OAuth Entity Profile with Correct Grant Type

⚠️ THIS IS THE #1 GOTCHA: The profile must have  grant_type = client_credentials . If set to  password  (the default), tokens are issued WITHOUT scopes and write-back silently fails — no errors anywhere.
Must use REST API: The ServiceNow UI ( oauth_entity_profile.list ) has an "OAuth provider" dropdown that only shows entities of type "OAuth Provider" (ADFS, Auth0, Azure AD, Google, Okta). Your  aws-devops-agent  entity is type "OAuth Client" and will NOT appear in the dropdown.
curl -s -u 'admin:PASSWORD' -X POST \
"https://<your-instance>.service-now.com/api/now/table/oauth_entity_profile" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{
"oauth_entity": "OAUTH_ENTITY_SYS_ID",
"name": "Default",
"default": "true",
"grant_type": "client_credentials"
}'
Verify (the grant_type sometimes doesn't persist):
curl -s -u 'admin:PASSWORD' \
"https://<your-instance>.service-now.com/api/now/table/oauth_entity_profile?sysparm_query=oauth_entity=OAUTH_ENTITY_SYS_ID&sysparm_fields=name,grant_type,default,sys_id" \
-H "Accept: application/json"
Response must show  "grant_type": "client_credentials" . If it shows  "password" , run the POST again.
Save the profile  sys_id  for step 3e.

3e: Link Scopes to Profile

Check if scopes exist for your entity:
curl -s -u 'admin:PASSWORD' \
"https://<your-instance>.service-now.com/api/now/table/oauth_entity_scope?sysparm_query=oauth_entity=OAUTH_ENTITY_SYS_ID&sysparm_fields=sys_id,name" \
-H "Accept: application/json"
If this returns an empty list — that's OK. The auth scope chain from steps 3a-3d is what matters. Skip this step.
If scopes are returned, link each to the profile:
curl -s -u 'admin:PASSWORD' -X POST \
"https://<your-instance>.service-now.com/api/now/table/oauth_entity_profile_scope" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"oauth_entity_profile": "PROFILE_SYS_ID", "oauth_entity_scope": "SCOPE_SYS_ID"}'

Step 4: Add incident_manager Role to OAuth User

# Find the incident_manager role sys_id
curl -s -u 'admin:PASSWORD' \
"https://<your-instance>.service-now.com/api/now/table/sys_user_role?sysparm_query=name=incident_manager&sysparm_fields=sys_id" \
-H "Accept: application/json"

# Find admin user sys_id
curl -s -u 'admin:PASSWORD' \
"https://<your-instance>.service-now.com/api/now/table/sys_user?sysparm_query=user_name=admin&sysparm_fields=sys_id" \
-H "Accept: application/json"

# Add the role (replace USER_SYS_ID and ROLE_SYS_ID)
curl -s -u 'admin:PASSWORD' -X POST \
"https://<your-instance>.service-now.com/api/now/table/sys_user_has_role" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"user": "USER_SYS_ID", "role": "ROLE_SYS_ID"}'
UI alternative: Navigate to  sys_user.list  → find System Administrator → Roles tab → Edit → add  incident_manager  → Save.

Step 5: Verify OAuth Setup

Test 1 — Token has correct scope:
curl -s -X POST "https://<your-instance>.service-now.com/oauth_token.do" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded"
Response must include  "scope": "devopsagent" :
{
"access_token": "VfboCl0RQ853Z6JWHxu6...",
"scope": "devopsagent",
"token_type": "Bearer",
"expires_in": 1799
}
If  scope  is empty ( "" ): Profile grant_type is wrong — go back to Step 3d.
Test 2 — Write-back works:
Create a test incident in ServiceNow, note its sys_id, then:
curl -s -X PATCH "https://<your-instance>.service-now.com/api/now/table/incident/INCIDENT_SYS_ID" \
-H "Authorization: Bearer TOKEN_FROM_TEST_1" \
-H "Content-Type: application/json" \
-d '{"comments": "test write-back from OAuth"}'
Expected: HTTP 200. Check the incident Comments tab for "test write-back from OAuth".
If you get 403 "Access to unscoped api is not allowed": Auth scope chain is broken — review Steps 3a-3e.



Part 2: Register ServiceNow in AWS DevOps Agent

Step 1: Register at Account Level

  1. Click Capability Providers in the left sidebar
  1. Find ServiceNow in the Communications section → click Register
  1. Fill in:
  • ServiceNow Instance URL:  https://<your-instance>.service-now.com 
  • Client ID: from Part 1, Step 2
  • Client Secret: from Part 1, Step 2
  1. Click Register

Step 2: Save Webhook Credentials

After registering, copy and save both values immediately:
  • Webhook URL:  https://event-ai.us-east-1.api.aws/webhook/servicenow/<uuid> 
  • Webhook Secret: Base64-encoded string
⚠️ Warning: You won't see these again after leaving this page. Both are needed for Part 4.

Step 3: Verify Registration

ServiceNow should appear under "Currently registered" on the Capability Providers page.



Part 3: Link ServiceNow to Agent Space

  1. In DevOps Agent console → Agent Spaces → click View details on your space
  1. Click the Capabilities tab
  1. Scroll to Communications → click Add
  1. Select ServiceNow → Save
Verify: Communications section shows ServiceNow with your instance ID.



Part 4: Configure ServiceNow Business Rule

A Business Rule is a server-side script that fires when incidents are created, sending a signed webhook to DevOps Agent.

Step 1: Create the Business Rule

  1. Navigate to System Definition → Business Rules → click New
  1. Fill in:
  • Name:  AWS DevOps Agent Webhook 
  • Table:  Incident [incident] 
  • Advanced: ✅ check this box
  1. In the When to run tab:
  • When:  after 
  • Insert: ✅ checked
  • Update: ❌ unchecked
  • Delete: ❌ unchecked
⚠️ Why Insert-only? Enabling Update causes an infinite loop: DevOps Agent writes findings → Business Rule fires → triggers another investigation → loop.

Step 2: Add the Script

Click the Advanced tab and paste:
(function executeRule(current, previous) {

var WEBHOOK_CONFIG = {
webhookSecret: GlideStringUtil.base64Encode('YOUR_WEBHOOK_SECRET'),
webhookUrl: 'YOUR_WEBHOOK_URL'
};

function generateHMACSignature(payloadString, secret) {
try {
var mac = new GlideCertificateEncryption();
var signature = mac.generateMac(secret, "HmacSHA256", payloadString);
return signature;
} catch (e) {
gs.error('HMAC generation failed: ' + e);
return null;
}
}

function callWebhook(payload, config) {
try {
var timestamp = new Date().toISOString();
var payloadString = JSON.stringify(payload);
var payloadWithTimestamp = timestamp + ':' + payloadString;

var signature = generateHMACSignature(payloadWithTimestamp, config.webhookSecret);

if (!signature) {
gs.error('Failed to generate signature');
return false;
}

var request = new sn_ws.RESTMessageV2();
request.setEndpoint(config.webhookUrl);
request.setHttpMethod('POST');
request.setRequestHeader('Content-Type', 'application/json');
request.setRequestHeader('x-amzn-event-signature', signature);
request.setRequestHeader('x-amzn-event-timestamp', timestamp);
request.setRequestBody(payloadString);

var response = request.execute();
var httpStatus = response.getStatusCode();

if (httpStatus >= 200 && httpStatus < 300) {
gs.info('Webhook sent successfully. Status: ' + httpStatus);
return true;
} else {
gs.error('Webhook failed. Status: ' + httpStatus);
return false;
}
} catch (ex) {
gs.error('Error sending webhook: ' + ex.getMessage());
return false;
}
}

var eventType = (current.operation() == 'insert') ? "create" : "update";

var incidentEvent = {
eventType: eventType.toString(),
sysId: current.sys_id.toString(),
number: current.number.toString(),
priority: current.priority.toString(),
shortDescription: current.short_description.toString(),
description: current.description.toString(),
incidentState: current.incident_state.toString()
};

if (WEBHOOK_CONFIG.webhookUrl && WEBHOOK_CONFIG.webhookSecret) {
callWebhook(incidentEvent, WEBHOOK_CONFIG);
}

})(current, previous);
Before saving, replace:
  •  YOUR_WEBHOOK_SECRET  → Webhook Secret from Part 2, Step 2
  •  YOUR_WEBHOOK_URL  → Webhook URL from Part 2, Step 2
Click Submit.
Note: The Business Rule may not appear in the admin UI due to scope filtering. Use  sys_script.list  to find it — it still fires correctly.



Part 5: Testing End-to-End

Step 1: Create Test Incident

  1. Navigate to Incident → Create New
  1. Fill in:
  • Caller:  System Administrator 
  • Short description:  Test DevOps Agent integration 
  • Description:  Testing automated investigation trigger 
  1. Click Submit

Step 2: Verify Webhook Sent

Navigate to System Logs → All → search for  Webhook sent successfully . You should see a recent entry with Status: 200.

Step 3: Verify Investigation Started

In the  DevOps Agent console  → Agent Spaces → View details → Launch web app. Verify a new investigation references your incident number.

Step 4: Verify Findings Posted Back

  1. Wait ~10 minutes for investigation to complete
  1. Return to your ServiceNow incident → Notes → Comments tab
  1. You should see comments containing:
  • "AWS DevOps Agent started the investigation"
  • Investigation findings, root causes, and observations
If "started" appears but no findings after 15 minutes: Token scope is empty — fix the profile grant_type (Part 1, Step 3d).



Critical Fixes & Lessons Learned

These are the implementation discoveries not covered in the official documentation:

1. Profile grant_type is the Silent Killer

Problem: Tokens issue successfully with empty scopes. No errors in any log. Write-back simply doesn't happen.
Root cause: OAuth Entity Profile defaults to  grant_type = password  instead of  client_credentials .
Fix: Must set via REST API (UI won't show OAuth Client entities):
curl -s -u 'admin:PASSWORD' -X PATCH \
"https://<your-instance>.service-now.com/api/now/table/oauth_entity_profile/PROFILE_SYS_ID" \
-H "Content-Type: application/json" -H "Accept: application/json" \
-d '{"grant_type": "client_credentials"}'

2. Auth Scope Requires a 5-Table Chain

The complete chain:  sys_auth_scope  →  sys_api_access_scope  →  oauth_entity_auth_scope_mapping  →  oauth_entity_profile  →  oauth_entity_profile_scope 
Missing any link = silent failure.

3. Steps 3c-3e Must Use REST API

ServiceNow UI dropdowns filter by entity type. "OAuth Client" entities don't appear in the "OAuth Provider" dropdown on  oauth_entity_profile.list . No workaround exists in the UI.

4. Business Rule Must Be Insert-Only

Update/Delete triggers cause investigation loops. DevOps Agent writes findings back → triggers Business Rule → new investigation → infinite loop.

5. Timestamp Must Be ISO Format

Use  new Date().toISOString() , not  GlideDateTime().getNumericValue() . The webhook signature validation expects ISO 8601.

6. Payload Must Be Flat

 shortDescription  must be at the top level of the JSON payload. Do NOT nest fields inside an  additionalContext  object — DevOps Agent expects a flat structure.

7. scope_restriction_status Doesn't Matter

The  scope_restriction_status  field on  oauth_entity  (restricted vs unrestricted) does NOT control write-back. The auth scope mapping chain is what matters.

8. DevOps Agent Posts Findings in Real-Time

Findings appear in ServiceNow comments during the investigation, not just at completion. This provides a live audit trail.

9. Business Rule May Not Show in Admin UI

ServiceNow scope filtering hides it. Use  sys_script.list  in the filter navigator to find and manage it.

10. Hidden Tables Require Full Name Entry

Tables like  sys_auth_scope.list ,  sys_api_access_scope.list  won't appear in the filter dropdown. Type the full name and press Enter — it navigates directly.



Troubleshooting Matrix

Investigation Not Triggered

Check
How to Verify
Business Rule is active
 sys_script.list  → find "AWS DevOps Agent Webhook" → Active = ✅
Webhook URL/secret correct
Open Business Rule → Advanced tab → verify values in script
Webhook sends successfully
 syslog.list  → search "Webhook sent successfully. Status: 200"
Webhook returns error
Search syslog for "Webhook failed" — status code indicates the issue

Findings Not Posted to ServiceNow (Most Common)

#
Check
Verification Command
Fix
1
Auth scope exists
 curl ... /sys_auth_scope?sysparm_query=name=devopsagent 
Create it (Step 3a)
2
Scope maps to Table API
 curl ... /sys_api_access_scope?sysparm_query=auth_scope=AUTH_SCOPE_SYS_ID 
Create mapping (Step 3b)
3
Scope mapped to OAuth entity
 curl ... /oauth_entity_auth_scope_mapping?sysparm_query=oauth_entity=ENTITY_SYS_ID 
Create mapping (Step 3c)
4
Profile grant_type = client_credentials
 curl ... /oauth_entity_profile?sysparm_query=oauth_entity=ENTITY_SYS_ID&sysparm_fields=grant_type 
Must show  client_credentials  (Step 3d)
5
OAuth user has incident_manager
 curl ... /sys_user_has_role?sysparm_query=user.user_name=admin^role.name=incident_manager 
Add role (Step 4)
6
Token has scope
Run token test (Step 5)
If empty, fix #4

Duplicate Investigations

Cause: Multiple webhooks triggering for the same incident.
Fix: Ensure Business Rule is Insert-only. If using additional integrations (e.g., Webex → DevOps Agent), disable duplicate paths.



HMAC Signing Reference

Property
Value
Algorithm
HMAC-SHA256
Timestamp format
ISO 8601 ( 2026-03-18T22:39:19.000Z )
Signing input
 timestamp + ":" + JSON.stringify(payload) 
Secret encoding
 GlideStringUtil.base64Encode(secret) 
Output
Base64
Headers
 x-amzn-event-signature ,  x-amzn-event-timestamp 

Webhook Payload Structure (Must Be Flat)

{
"eventType": "create",
"sysId": "85be08d8837b72102749e7d0deaad3bd",
"number": "INC0010025",
"priority": "2",
"shortDescription": "pet-tracker 502 errors",
"description": "pet-tracker service in us-west-2 returning 502 errors...",
"incidentState": "1"
}



Conclusion

This integration eliminates the manual handoff between ITSM and cloud investigation. When properly configured, the entire flow — from incident creation to root cause findings posted back — happens automatically in under 15 minutes.
The critical takeaway: the auth scope configuration (Part 1, Step 3) is where most implementations fail, and the failures are completely silent. If you follow the 5-table chain and verify the token scope before proceeding, the rest of the setup is straightforward.
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article