Webhooks

Webhooks allow ServiceNow to notify 2501 immediately when an incident is created or updated, instead of waiting for the next polling cycle. Each webhook registration generates a unique URL and shared secret that you configure on the ServiceNow side.

Creating a Webhook

Use the 2501-infra CLI to register a new webhook:

2501-infra webhook create \
  --name <name> \
  --source-type <source> \
  --event-type <event> \
  --gateway-id <gateway-id>

Parameters

Parameter	Required	Description
`--name`	Yes	Human-readable name for this webhook (e.g., `prod-incidents`, `staging`)
`--source-type`	Yes	Ticketing system type (e.g., `servicenow`)
`--event-type`	Yes	Resource type this webhook receives (e.g., `incident`, `change_request`)
`--gateway-id`	No	Target gateway ID. Auto-selected if only one active gateway exists
`--description`	No	Optional description for this webhook

Example

2501-infra webhook create \
  --name prod-incidents \
  --source-type servicenow \
  --event-type incident \
  --gateway-id gtw_a1b2c3d4-...

Output:

Gateway: gtw_a1b2c3d4-...

Webhook created!
  ID:         whk_e5f6a7b8-...
  URL:        https://cmd.example.com/api/webhooks/ingest/4f8a2c1e9b3d7a0f6e5c8d2b
  Secret:     a1b2c3d4...
  Event type: incident
  Gateway:    gtw_a1b2c3d4-...

--- ServiceNow Business Rule configuration ---

  Table:            incident [incident]
  Active:           ✓
  Advanced:         ✓
  When:             after
  Insert:           ✓
  Update:           ✓
  Filter Conditions:
    Assignment group is <your group>
    Active is true

--- Script (paste into Advanced tab) ---

(function executeRule(current, previous) {
    try {
        var request = new sn_ws.RESTMessageV2();
        request.setEndpoint('https://cmd.example.com/api/webhooks/ingest/4f8a2c1e9b3d7a0f6e5c8d2b');
        request.setHttpMethod('POST');
        request.setRequestHeader('Content-Type', 'application/json');
        request.setRequestHeader('X-Webhook-Secret', 'a1b2c3d4...');
        request.setRequestBody(JSON.stringify({
            sys_id: current.getUniqueValue()
        }));
        request.setHttpTimeout(5000);
        request.executeAsync();
    } catch (e) {
        gs.error('2501 webhook failed: ' + e.message);
    }
})(current, previous);

Configuring ServiceNow

After creating a webhook, configure ServiceNow to send events to it using a Business Rule.

Business Rule

In ServiceNow, navigate to System Definition > Business Rules
Click New
Configure:
- Name: a descriptive name (e.g., 2501 Webhook - Incidents)
- Table: incident (or the table matching your --event-type)
- When: after
- Insert: checked
- Update: checked
Check Advanced
Paste the generated script into the Script field
Optionally add a Filter Condition to scope which incidents trigger the webhook (e.g., Assignment group is <your group>)
Click Submit

Only the incident table is currently supported. change_request and other tables are not yet supported.

Deleting a Webhook

2501-infra webhook delete --id whk_e5f6a7b8-...

This removes the webhook registration from 2501. You should also deactivate or delete the corresponding Business Rule in ServiceNow.

Network Requirements

The ServiceNow instance must be able to reach your Command Center’s URL over HTTPS. The webhook endpoint is:

POST https://<your-command-center>/api/webhooks/ingest/<path>

How It Works

ServiceNow fires the Business Rule when an incident is created or updated
The script sends a POST request with the incident’s sys_id to the webhook URL
Command Center proxies the request to the engine
The engine validates the shared secret, then enqueues the ticket for processing
The engine fetches the full incident details from ServiceNow and processes it through the gateway pipeline

Webhooks are complemented by a polling reconciliation that runs every ~2 minutes, ensuring no incidents are missed even if a webhook delivery fails.

Getting Started

Deployment

Core Concepts

Configure

Scenario Runner

CLI

Creating a Webhook

Parameters

Example

Configuring ServiceNow

Business Rule

Deleting a Webhook

Network Requirements

How It Works

​Creating a Webhook

​Parameters

​Example

​Configuring ServiceNow

​Business Rule

​Deleting a Webhook

​Network Requirements

​How It Works

Creating a Webhook

Parameters

Example

Configuring ServiceNow

Business Rule

Deleting a Webhook

Network Requirements

How It Works