Webhooks - 2501.ai

Webhooks allow ServiceNow to notify 2501 immediately when an incident or change request 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:

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

Both the incident and change_request tables are supported. A gateway that handles incidents and changes uses two webhooks, one per table, each with its own Business Rule. For how change requests are picked up and executed, see Change Requests.

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 a record (incident or change request) is created or updated
The script sends a POST request with the record’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 record details from ServiceNow and processes it through the gateway pipeline

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

​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