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

# Grafana Webhook Setup Guide

> Configure Grafana to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/grafana#getting-started) on the Grafana connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Receive Grafana webhook events</h2>

  <p>StackOne creates and manages the webhook subscriptions automatically when the account is connected, and removes them when the account is disconnected. There are no manual steps in Grafana.<br /><br />Alerting events arrive through a webhook contact point named `StackOne Events` and a notification policy route that forwards every alert to it. The route is added with continue enabled, so your existing contact points keep receiving alerts. IRM events arrive through one IRM outgoing webhook per selected event, named `StackOne Events - <trigger>`. StackOne finds your IRM API URL automatically from the Grafana IRM app.</p>

  <ul>
    <li>Alerting events require the `alert.provisioning:write` permission (included in the <strong>Editor</strong> and <strong>Admin</strong> roles).</li>
    <li>IRM events require the `grafana-irm-app.outgoing-webhooks:write` permission (included in the <strong>Admin</strong> role) and the Grafana IRM app enabled on the stack.</li>
    <li>Only alerts from Grafana-managed alert rules are delivered as Alerting events.</li>
  </ul>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following Grafana events can be enabled. Only events selected in StackOne are subscribed.</p>

  <Steps>
    <Step title="Alert events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from Grafana Alerting rule state changes.</p>

        <ul>
          <li><strong>Alert Firing Event</strong> (`alert.firing`) — Fired when one or more alert instances of a rule start firing</li>
          <li><strong>Alert Resolved Event</strong> (`alert.resolved`) — Fired when every alert instance in a notification group returns to normal</li>
        </ul>
      </div>
    </Step>

    <Step title="IRM alert group events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from Grafana IRM alert groups.</p>

        <ul>
          <li><strong>IRM Alert Group Created</strong> (`alert group created`) — Fired when a new IRM alert group is created from an incoming alert</li>
          <li><strong>IRM Alert Group Acknowledged</strong> (`acknowledge`) — Fired when an alert group is acknowledged</li>
          <li><strong>IRM Alert Group Resolved</strong> (`resolve`) — Fired when an alert group is resolved</li>
          <li><strong>IRM Alert Group Silenced</strong> (`silence`) — Fired when an alert group is silenced (event.until carries the silence end)</li>
          <li><strong>IRM Alert Group Unsilenced</strong> (`unsilence`) — Fired when a silenced alert group is unsilenced</li>
          <li><strong>IRM Alert Group Unresolved</strong> (`unresolve`) — Fired when a resolved alert group is reopened</li>
          <li><strong>IRM Alert Group Unacknowledged</strong> (`unacknowledge`) — Fired when an acknowledgement is removed from an alert group</li>
          <li><strong>IRM Alert Group Escalation</strong> (`escalation`) — Fired when an escalation chain reaches a Trigger webhook step that references the StackOne webhook</li>
          <li><strong>IRM Alert Group Status Changed</strong> (`status change`) — Fired when an alert group changes state (acknowledge, resolve, silence, unsilence, unresolve, or unacknowledge); event.type carries the underlying action</li>
          <li><strong>IRM Alert Group Personal Notification</strong> (`personal notification`) — Fired when IRM sends a personal notification to a user for an alert group (event.user carries the notified user)</li>
        </ul>
      </div>
    </Step>

    <Step title="IRM schedule events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from Grafana IRM on-call schedules. Available in Grafana Cloud IRM only.</p>

        <ul>
          <li><strong>IRM Schedule On-Call Changed</strong> (`on-call changed`) — Fired when the set of users on call for a schedule changes</li>
          <li><strong>IRM Schedule Shift Started</strong> (`shift started`) — Fired when an on-call shift starts in a schedule</li>
          <li><strong>IRM Schedule Shift Ended</strong> (`shift ended`) — Fired when an on-call shift ends in a schedule</li>
          <li><strong>IRM Schedule Going On-Call</strong> (`going on-call`) — Fired when a user is about to go on call (shift carries the start and end)</li>
        </ul>
      </div>
    </Step>

    <Step title="IRM shift swap events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events from Grafana IRM shift swap requests. Available in Grafana Cloud IRM only.</p>

        <ul>
          <li><strong>IRM Shift Swap Created</strong> (`shift swap created`) — Fired when a shift swap request is created</li>
          <li><strong>IRM Shift Swap Taken</strong> (`shift swap taken`) — Fired when a shift swap request is taken by another user</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Grafana delivers events to StackOne.</p>

  <Steps>
    <Step title="Grouped alert notifications">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each Alerting request is one Grafana notification that can contain several alert instances in its `alerts` list. StackOne groups notifications by alert rule name, and the event identifier is the alert rule UID of the first alert. The full notification is included in the event data.</p>
      </div>
    </Step>

    <Step title="IRM deliveries">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each IRM request carries one event. The event identifier is the alert group, schedule, or shift swap request ID, and the event date is the IRM event time. Enabling <strong>IRM Alert Group Status Changed</strong> together with the individual state events delivers each state change twice (once per event). The <strong>IRM Alert Group Escalation</strong> event only fires when an escalation chain includes a <strong>Trigger webhook</strong> step that uses the `StackOne Events - escalation` webhook.</p>
      </div>
    </Step>

    <Step title="Signed requests">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>On Grafana 12 and later, Alerting requests are signed with HMAC-SHA256 in the `X-Grafana-Alerting-Signature` header. Grafana IRM does not sign outgoing webhooks.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.