> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/oncall-assistant.md).

# Using On-call Assistant for incident notifications

Cortex’s On-call Assistant leverages the [PagerDuty integration](/ingesting-data-into-cortex/integrations/pagerduty.md) to automatically surface the most vital information about entity health and metadata when an incident is triggered. On-call Assistant notifies the user(s) responsible for an incident via Slack, including information about the affected entity, recent deployments, ownership, and links to get more details, including dependencies, runbooks, and logs.

On-call Assistant helps users respond to incidents in real time, simplifying the incident response process and helping to reduce MTTR. It can also drive adoption and engagement through links to the catalogs and Scorecards.

{% hint style="info" %}
On-call Assistant only works for **service-level** PagerDuty registrations, since these notifications are related to affected services. Refer to [this article](/ingesting-data-into-cortex/integrations/pagerduty/connecting-entities-to-pagerduty.md#considerations-for-registering-pagerduty-entities) for more information.
{% endhint %}

## How On-call Assistant notifications are sent in Slack

When a PagerDuty incident is triggered, Cortex identifies the responsible on-call user and notifies them in Slack. The alert includes information about the affected entity, deploy details, and ownership information. A direct link is included to view the alert in PagerDuty, so the incident can be quickly assessed from its source.

**Individual users** - On-call Assistant sends a direct message (DM) to the on-call user. Users don't need to install the Cortex Slack app or select a channel. Cortex looks up the user's Slack account using the email address on their Cortex account, then sends the DM directly. The only requirement is that the user's email in Cortex matches their Slack workspace email.

**Teams** - Notifications are sent to the Slack channel or channels [configured on the entity](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant.md#connecting-an-entity-to-a-slack-channel).

<div align="left" data-with-frame="true"><img src="/files/Y6kiXAoQphrCjOcPyHIW" alt="On-call assistant notifies users via Slack." width="375"></div>

### Viewing runbooks and other links

<div align="left" data-with-frame="true"><img src="/files/Y9t5j8pSNDwqleyvPg4l" alt="" width="563"></div>

### Viewing dependencies

<div align="left" data-with-frame="true"><img src="/files/9NpkbWQgzLufuFtJBISF" alt="" width="563"></div>

## Enabling On-call Assistant

### Prerequisites

1. An [API key](https://support.pagerduty.com/main/docs/api-access-keys#rest-api-keys) in PagerDuty with the `Write` permission.&#x20;
   * If you choose to bypass this prerequisite and create an API key with `Read-only` permissions, you also need to [configure a webhook](#configuring-a-webhook-for-read-only-api-keys) to get the On-call Assistant working.
2. The [PagerDuty integration](/ingesting-data-into-cortex/integrations/pagerduty.md) must be configured.
   * If using an API key with `Read-only` permission, be sure to toggle on **Read-only API key** in the PagerDuty side panel.<br>

     <div align="left" data-with-frame="true"><figure><img src="/files/ckhit4z3ilWuH6f6v7fu" alt="The &#x27;Read-only API key&#x27; option toggled on." width="113"><figcaption></figcaption></figure></div>
3. If sending notifications to teams, Slack channels must be [configured on the entity](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant.md#connecting-an-entity-to-a-slack-channel).

### **Enabling On-call Assistant in Cortex**

1. From the main sidebar, select **Integrations**.
2. Locate PagerDuty, then click **Settings**.
3. Toggle on **Enable On-call Assistant**.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/Nx0Kwxj1zoLVwntC2Lqm" alt="The &#x27;Enable On-call Assistant&#x27; option toggled on." width="375"><figcaption></figcaption></figure></div>

#### Configuring a webhook for read-only API keys

If your PagerDuty API key has `Read-only` permissions, you must also configure a webhook subscription.

**Step 1: Enabling On-call Assistant in Cortex**

1. From the main sidebar, select **Integrations**.
2. Locate PagerDuty, then click **Settings**.
3. Toggle on **Enable On-call Assistant**. The **Configure webhook** side panel opens.

**Step 2: Adding a webhook in PagerDuty**

1. In PagerDuty, add a new [webhook](https://support.pagerduty.com/main/docs/webhooks):
   1. Under Webhook URL, paste the Cortex webhook URL. The Cortex webhook URL can be found in the **Configure webhook** side panel.<br>

      <div align="left" data-with-frame="true"><figure><img src="/files/qKd55tAmDK6qpFokYBjx" alt="The webhook URL." width="375"><figcaption></figcaption></figure></div>
   2. From the **Scope type** dropdown, select **Account**.
   3. Under **Event Subscription**, clear all checkboxes EXCEPT:
      * `incident.escalated`
      * `incident.reopened`
      * `incident.triggered`
      * `incident.unacknowledged`&#x20;
   4. Click **Add webhook**. The **Webhook subscription created** window opens.
   5. Copy the webhook secret. Don't skip this step! You'll need the webhook secret to complete the setup.
   6. Click **OK**.

**Step 3: Completing setup in Cortex**&#x20;

1. Go back to the browser window where your Cortex instance is open.
2. In the Configure webhook side panel, paste the webhook secret in the **Secret** field.<br>

   <div align="left" data-with-frame="true"><figure><img src="/files/QWvMm7TvgjOvTsB1eU2y" alt="" width="178"><figcaption></figcaption></figure></div>
3. Click **Save**.