ServiceNow
Agent-driven production changes enter the change management process your organization already trusts. Import one Update Set, paste one key, and every ActPass approval can flow through a ServiceNow change_request.
Why ServiceNow customers use ActPass
Your change advisory board already governs human-initiated production changes. AI agents create the same class of risk without entering that process. The ActPass bridge maps every require_approval decision to a change_request — risk-mapped from the ActPass risk tier (critical→1 … none→4), categorized as AI Agent Action, and correlated by u_actpass_approval_id — so agent actions get the same reviewers, SLAs, and audit trail as any other change.
Install (3 steps)
Your instance runs only an imported Update Set — no ActPass source code, no outbound credential by default.
| Step | Where | What happens |
|---|---|---|
| 1. Import the Update Set | System Update Sets → Retrieved Update Sets → Import from XML | Adds the u_actpass_approval_id column, x_actpass.* properties, the notify business rule, and an off-by-default pull-mode job. |
| 2. Paste your gateway key | sys_properties.list → x_actpass.gateway_key | A gateway-scope API key from Settings → API keys. Readonly/device keys are rejected (403). |
| 3. Register the install | One curl from anywhere | Tells ActPass which instance you are; unlocks the webhook (unregistered instances get 404). |
curl -X POST https://www.api.actpass.org/api/v1/integrations/installs \
-H "Authorization: Bearer <owner/admin/security_admin API key>" \
-H "content-type: application/json" \
-d '{ "channel": "servicenow", "external_id": "<instance>", "config": {} }'Done: when a tagged change_request is approved or rejected, your instance POSTs the decision to /api/v1/integrations/servicenow/webhook and ActPass applies it to the matching approval — idempotently, so retries are safe.
Three modes, one webhook
| Mode | ServiceNow credential given to ActPass? | change_request creation |
|---|---|---|
| Inbound-only (default) | No | You open/tag change_requests yourself; decisions flow back automatically. |
| Push (optional) | Yes — encrypted service account | ActPass opens a risk-mapped change_request the moment an approval is created. |
| Pull (optional) | No — zero-credential | A scheduled job inside your instance polls pending approvals and opens de-duplicated change_requests. |
Push mode
Create a service account whose ACLs allow inserting into change_request only, then re-run install step 3 with config.auth set (basic or bearer). The credential is AES-256-GCM envelope-encrypted, bound to your tenant, and never returned by any API. A failed create never blocks the approval — it stays decidable in the dashboard.
Pull mode (zero-credential)
Set x_actpass.pull_mode to true and confirm the scheduled job is active. The job polls GET /api/v1/approvals?status=pending with the gateway key already in your instance, de-duplicates on u_actpass_approval_id, and processes up to 200 pending approvals per poll.
Security model
| Property | Guarantee |
|---|---|
| Tenant binding | The tenant is resolved from the authenticated gateway key, never from the webhook body. |
| Key scope | Only gateway-scope keys can decide; readonly and device keys get 403. |
| Setup gate | No registered install for the tenant → 404. Nothing decides before setup completes. |
| Idempotency | Retries of an already-decided approval return 200 {"status":"already_decided"}. |
| Fail closed | A failed push create, an unmappable state, or a missing key never auto-approves anything. |
Get the package
The distribution unit is self-contained: the Update Set XML, the install README, and the distribution guide, delivered as a checksummed zip. Ask your ActPass contact for the latest actpass-servicenow-bridge-<version>.zip and verify the .sha256 before importing into production.
Endpoint reference
| Endpoint | Direction | Auth |
|---|---|---|
| POST /api/v1/integrations/servicenow/webhook | ServiceNow → ActPass decision | gateway key |
| POST /api/v1/integrations/installs | register install / push credential | key.write (owner/admin/security_admin) |
| GET /api/v1/approvals/{id} | agent polls the decision | any tenant key |