Skip to main content
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

ParameterRequiredDescription
--nameYesHuman-readable name for this webhook (e.g., prod-incidents, staging)
--source-typeYesTicketing system type (e.g., servicenow)
--event-typeYesResource type this webhook receives (e.g., incident, change_request)
--gateway-idNoTarget gateway ID. Auto-selected if only one active gateway exists
--descriptionNoOptional 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

  1. In ServiceNow, navigate to System Definition > Business Rules
  2. Click New
  3. 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
  4. Check Advanced
  5. Paste the generated script into the Script field
  6. Optionally add a Filter Condition to scope which incidents trigger the webhook (e.g., Assignment group is <your group>)
  7. 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

  1. ServiceNow fires the Business Rule when an incident is created or updated
  2. The script sends a POST request with the incident’s sys_id to the webhook URL
  3. Command Center proxies the request to the engine
  4. The engine validates the shared secret, then enqueues the ticket for processing
  5. 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.