> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Set up real-time webhook notifications from ServiceNow

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:

```bash theme={null}
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

```bash theme={null}
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**

<Note>
  Only the `incident` table is currently supported. `change_request` and other tables are not yet supported.
</Note>

## Deleting a Webhook

```bash theme={null}
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](/0.4/core-concepts/gateways) pipeline

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