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
-
curlcommand-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
- Navigate to
sys_properties.list(type in filter navigator → press Enter)
- Click New
- Fill in:
- Name:
glide.oauth.inbound.client.credential.grant_type.enabled
- Value:
true
- Type:
true | false
- Click Submit
Verify: Search for "glide.oauth" in the properties list — confirm Value =
true .Step 2: Create OAuth Application
- Navigate to System OAuth → Inbound Integrations
- Click New → Select OAuth - Client Credentials Grant
- Fill in:
- Name:
aws-devops-agent
- OAuth application user: Search for and select
System Administrator(must be admin — lesser roles cause API access issues)
- Click Submit
- ⚠️ 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 havegrant_type = client_credentials. If set topassword(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). Youraws-devops-agententity 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_idcurl -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_idcurl -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
- Open the AWS DevOps Agent console
- Click Capability Providers in the left sidebar
- Find ServiceNow in the Communications section → click Register
- 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
- 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
- In DevOps Agent console → Agent Spaces → click View details on your space
- Click the Capabilities tab
- Scroll to Communications → click Add
- 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
- Navigate to System Definition → Business Rules → click New
- Fill in:
- Name:
AWS DevOps Agent Webhook
- Table:
Incident [incident]
- Advanced: ✅ check this box
- 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. Usesys_script.listto find it — it still fires correctly.
Part 5: Testing End-to-End
Step 1: Create Test Incident
- Navigate to Incident → Create New
- Fill in:
- Caller:
System Administrator
- Short description:
Test DevOps Agent integration
- Description:
Testing automated investigation trigger
- 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
- Wait ~10 minutes for investigation to complete
- Return to your ServiceNow incident → Notes → Comments tab
- 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.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article