> ## 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 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:

```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:

```
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>
  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](/0.7/core-concepts/gateways#change-requests).
</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 a record (incident or change request) is created or updated
2. The script sends a POST request with the record'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 record details from ServiceNow and processes it through the [gateway](/0.7/core-concepts/gateways) pipeline

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