# Webhooks

Receive signed, real-time HTTP callbacks from Risotto when events happen in your organization

Webhooks let Risotto notify your systems in real time when events happen in your
organization. When you register an endpoint, Risotto sends a signed HTTP `POST`
request to your URL each time a subscribed event occurs so you can trigger
downstream automation, sync data to another system, or build custom workflows
without polling the [API](https://www.tryrisotto.com/docs/dashboard/settings/developers/api-keys).

You configure webhooks in the Risotto Dashboard under **Settings > Developers >
Webhooks**.

## Create an endpoint

1. **Open the Webhooks settings**

   In the Dashboard, go to **Settings > Developers > Webhooks**.

2. **Add an endpoint**

   Click **Add Endpoint** (or **Add Your First Endpoint** if you have no
   endpoints). In the **Add Webhook Endpoint** dialog, enter the HTTPS URL where
   Risotto should deliver events in **Endpoint URL**.

3. **Select event types**

   Under **Events**, select the [event types](#event-types) this endpoint should
   receive. An endpoint only receives events it is subscribed to. Click **Add
   Endpoint**.

4. **Save the signing secret**

   When the endpoint is created, the **Webhook Endpoint Created** dialog displays its **signing secret**
   (prefixed with `whsec_`) **once**. Copy it and store it securely. You will
   need it to [verify signatures](#verifying-signatures), and it cannot be
   retrieved again after you close the dialog.

> **Warning:** The signing secret is shown in full only at creation time. Afterward the
> Dashboard displays a redacted placeholder. If you lose the secret, delete and
> recreate the endpoint to generate a new one.

### Send one event to more than one endpoint

You can add more than one endpoint, and several endpoints can subscribe to the same event type. For example, one endpoint can send `comment.added` to a test receiver and a second endpoint can send it to production.

- Risotto sends each event to every enabled endpoint that subscribes to it.
- Each endpoint has its own signing secret, [retries](#retry-schedule), [auto-disable](#auto-disable), and [delivery log](#delivery-logs-and-testing). A failure at one endpoint does not delay the others.
- All endpoints get events from your live organization. A test receiver gets real events, not sample data.
- The event `id` is the same at every endpoint that gets the event.

> **Note:** Endpoint URLs must use HTTPS. Risotto validates each URL before delivery and
> blocks requests to internal or private network addresses. Risotto also refuses
> a URL that has a backslash before the path or a host with non-ASCII
> characters. For an international domain name, write the punycode form, for
> example `xn--bcher-kva.example`.

## Event types

Subscribe an endpoint to one or more of the following event types:

| Event type                  | Triggered when                                                              |
| --------------------------- | --------------------------------------------------------------------------- |
| `ticket.created`            | A new ticket is created from any request source.                            |
| `ticket.escalated`          | A ticket is escalated to human support.                                     |
| `comment.added`             | A public comment is added to a ticket. Internal notes do not fire it.       |
| `ticket.closed`             | A ticket reaches a final status, with how it closed.                        |
| `access.requests.completed` | A request ticket is resolved, with the granted/denied outcome for each app. |

> **Note:** There is no separate `ticket.resolved` event. Subscribe to `ticket.closed` and
> read its `closure_state` field to tell a resolved ticket from one that was
> closed or canceled.

## Payload format

Every delivery is a `POST` request with a compact JSON body using a consistent
envelope. The top-level fields are the same for every event; only the `data`
object changes shape based on the event `type`.

| Field        | Description                                                                |
| ------------ | -------------------------------------------------------------------------- |
| `id`         | Unique identifier for the event. Stable across retries — use it to dedupe. |
| `type`       | The [event type](#event-types) that triggered the delivery.                |
| `created_at` | ISO 8601 timestamp of when the event occurred.                             |
| `data`       | The affected resource. Its shape depends on the event `type` (below).      |

### Event payloads

Expand an event type to see its `data` fields and an example delivery.

#### ticket.created

Fires when a new ticket is created from any request source. Its `data`
object is the full ticket, with the same fields as the
`GET /v1/tickets/{ticket_id}` response. The main fields are:

| Field                | Description                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `ticket_id`          | The new ticket's identifier.                                                                                                                |
| `title`              | The ticket's title.                                                                                                                         |
| `status`             | The ticket's current status, such as `open`.                                                                                                |
| `source`             | Where the ticket originated, such as `slack`.                                                                                               |
| `requestor`          | The person who created the ticket, as `{ email, name }`.                                                                                    |
| `priority`           | The ticket's priority, as `{ value, is_suggested }`, or `null`. See [Ticket priority](#ticket-priority).                                    |
| `external_ticket_id` | The key of the synced ticket in your ticketing system. Risotto sends this event before it syncs the ticket, so the value is usually `null`. |
| `created_at`         | ISO 8601 timestamp of when the ticket was created.                                                                                          |

```json
{
  "id": "evt_01H9XZ...",
  "type": "ticket.created",
  "created_at": "2026-07-15T17:04:22Z",
  "data": {
    "ticket_id": "TCK-1234",
    "title": "Access request for GitHub",
    "status": "open",
    "source": "slack",
    "requestor": { "email": "jordan@example.com", "name": "Jordan Lee" },
    "priority": { "value": "medium", "is_suggested": true },
    "external_ticket_id": null,
    "created_at": "2026-07-15T17:04:20Z"
  }
}
```

#### ticket.escalated

Fires when a ticket is escalated to human support. Unlike `ticket.created`,
this event is also sent for tickets that originate in an external ticketing
system. Its `data` object contains the same fields as
[`ticket.created`](#ticket-created), plus two escalation fields:

| Field          | Description                                                               |
| -------------- | ------------------------------------------------------------------------- |
| `escalated_at` | ISO 8601 timestamp of when the ticket was escalated to human support.     |
| `reason`       | Why the ticket was escalated, if a reason was provided; otherwise `null`. |

```json
{
  "id": "evt_01H9XZ...",
  "type": "ticket.escalated",
  "created_at": "2026-07-15T17:04:22Z",
  "data": {
    "ticket_id": "TCK-1234",
    "title": "Access request for GitHub",
    "status": "waiting_for_support",
    "source": "slack",
    "requestor": { "email": "jordan@example.com", "name": "Jordan Lee" },
    "created_at": "2026-07-15T17:04:20Z",
    "escalated_at": "2026-07-15T17:05:10Z",
    "reason": "Requestor needs admin access not covered by an access rule."
  }
}
```

#### comment.added

Fires when a public comment is added to a ticket. Its `data` object contains:

| Field          | Description                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------- |
| `content`      | The text of the comment.                                                                                    |
| `author_name`  | The display name of the author. For a reply from Risotto, the bot name.                                     |
| `author_email` | The email address of the author, or `null` for a reply from Risotto.                                        |
| `created`      | ISO 8601 timestamp of when the comment was added.                                                           |
| `is_internal`  | Always `false`. Internal notes do not fire this event.                                                      |
| `source`       | Where the comment came from, such as `slack`, `msteams`, `email`, `dashboard`, `api`, `jira`, or `risotto`. |
| `ticket_id`    | The ticket the comment was added to, such as `IT-123`.                                                      |
| `department`   | The department of the ticket, as `{ id, name, ticket_prefix }`.                                             |

```json
{
  "id": "evt_01H9XZ...",
  "type": "comment.added",
  "created_at": "2026-07-15T17:04:22Z",
  "data": {
    "content": "Thanks, that worked.",
    "author_name": "Morgan Diaz",
    "author_email": "morgan@example.com",
    "created": "2026-07-15T17:04:21Z",
    "is_internal": false,
    "source": "slack",
    "ticket_id": "IT-123",
    "department": { "id": "8f0e...", "name": "IT", "ticket_prefix": "IT" }
  }
}
```

The event fires for every author and every channel, also for a ticket that is resolved or closed:

- Risotto's own replies fire it, with `source` set to `risotto` and `author_email` set to `null`.
- A comment that you post with the API fires it too. To skip your own comments, filter on `source`.
- The text of a new request does not fire it. That text is in [`ticket.created`](#ticket-created).
- In a Microsoft Teams channel thread, a reply to a finished ticket that does not tag Risotto is not saved, so it does not fire the event. In Slack, the same reply is saved and fires the event.

The payload does not include the ticket's status or the author's role. To find out whether the requestor wrote the comment, or whether the ticket is open again, get the ticket with `GET /v1/tickets/{ticket_id}` and compare `author_email` with `requestor.email`. There is no reopen event. A reopen can happen just after the comment event is sent, so the status that you read can still be `resolved`. See [Reopening a finished ticket](https://www.tryrisotto.com/docs/concepts/ticket-lifecycle#reopening-a-finished-ticket).

#### ticket.closed

Fires once when a ticket first reaches a final status. A ticket that moves
from one final status to another (for example, `resolved` to `closed`) does
not fire again. A ticket that is reopened and closed again fires again.
Like `ticket.escalated`, this event is also sent for tickets that
originate in an external ticketing system.

Its `data` object is the full ticket, with the same fields as the
`GET /v1/tickets/{ticket_id}` response (including `request_text`,
`assignee`, `department`, `priority`, `tags`, `custom_fields`, `comments`,
and `resolved_at`), plus one field:

| Field           | Description                                                                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `closure_state` | How the ticket closed: `resolved` (the request was fulfilled), `closed` (closed without resolution, including duplicates), or `canceled` (the requestor withdrew it). |

`closure_state` is not a ticket status. A canceled ticket has `status`
`closed` and `closure_state` `canceled`.

> **Note:** A closure synced in from Linear, Zendesk, or Airtable (someone closes the
> linked issue in that system) updates the Risotto ticket's status but does
> not fire `ticket.closed`. Closures made in Risotto (chat, the dashboard,
> the API) and closures synced from Jira or Freshservice fire it.

```json
{
  "id": "evt_01H9XZ...",
  "type": "ticket.closed",
  "created_at": "2026-07-15T18:10:02Z",
  "data": {
    "ticket_id": "TCK-1234",
    "title": "Access request for GitHub",
    "request_text": "Can I get access to the GitHub org?",
    "status": "resolved",
    "source": "slack",
    "requestor": { "email": "jordan@example.com", "name": "Jordan Lee" },
    "assignee": null,
    "department": { "id": "660e8400-...", "name": "IT Support", "ticket_prefix": "TCK" },
    "priority": { "value": "high", "is_suggested": false },
    "tags": ["Auto-Solved"],
    "created": "2026-07-15T17:04:20Z",
    "modified": "2026-07-15T18:10:00Z",
    "resolved_at": "2026-07-15T18:10:00Z",
    "comments": [],
    "external_ticket_id": null,
    "external_ticket_url": null,
    "message_url": "https://example.slack.com/archives/C123/p1720000000000000",
    "closure_state": "resolved"
  }
}
```

#### access.requests.completed

Fires once per request ticket when the ticket reaches a terminal state
(resolved, closed, or duplicate), and batches the outcome of every access
request on that ticket. Its `data` object contains:

| Field          | Description                                                         |
| -------------- | ------------------------------------------------------------------- |
| `ticket_id`    | The resolved ticket's identifier.                                   |
| `requestor`    | The person who made the request, as `{ email, name }`.              |
| `completed_at` | ISO 8601 timestamp of when the ticket was resolved.                 |
| `requests`     | Array of the individual access requests and their outcomes (below). |

Each item in `requests` describes one user/application request:

| Field              | Description                                                                 |
| ------------------ | --------------------------------------------------------------------------- |
| `workflow_uuid`    | Identifier of the request, for correlation. Use this field.                 |
| `workflow_id`      | Deprecated integer identifier of the request. Use `workflow_uuid`.          |
| `software`         | Name of the application requested.                                          |
| `status`           | Outcome: `granted`, `denied`, `canceled`, or `escalated`.                   |
| `grantee`          | The user the access is for, as `{ email, name }`.                           |
| `reason`           | Reason associated with the outcome, if any.                                 |
| `resolved_at`      | ISO 8601 timestamp of when this request was resolved.                       |
| `expires_at`       | When granted access expires, or `null` for permanent or non-granted access. |
| `granted_by_email` | Email of the granter, set only for manual grants.                           |
| `access_rule`      | The matched access rule, as `{ rule_id, software_name, app_id, app_name }`. |

```json
{
  "id": "evt_01H9XZ...",
  "type": "access.requests.completed",
  "created_at": "2026-07-15T17:04:22Z",
  "data": {
    "ticket_id": "TCK-1234",
    "requestor": { "email": "jordan@example.com", "name": "Jordan Lee" },
    "completed_at": "2026-07-15T17:04:20Z",
    "requests": [
      {
        "workflow_uuid": "019a3b2c-1d4e-7f00-8a00-000000098765",
        "workflow_id": 98765,
        "software": "GitHub",
        "status": "granted",
        "grantee": { "email": "jordan@example.com", "name": "Jordan Lee" },
        "reason": null,
        "resolved_at": "2026-07-15T17:04:19Z",
        "expires_at": "2026-08-14T17:04:19Z",
        "granted_by_email": null,
        "access_rule": {
          "rule_id": "4f6c2a1e-8b3d-4e5f-9a7b-2c1d0e9f8a76",
          "software_name": "GitHub",
          "app_id": "9b2e7d4c-3a1f-4c8e-b6d5-1e0f2a3b4c5d",
          "app_name": "GitHub"
        }
      }
    ]
  }
}
```

### Ticket priority

The `ticket.created`, `ticket.escalated`, and `ticket.closed` payloads include `priority`. The same field is in the `/v1/tickets` API responses and in the ticket tools of the [MCP server](https://www.tryrisotto.com/docs/integrations/mcp-server). It has two fields:

| Field          | Description                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| `value`        | `low`, `medium`, `high`, or `urgent`.                                                                |
| `is_suggested` | `false` when a person set the priority. `true` when the value is the priority that the AI suggested. |

A priority that a person sets replaces the suggested priority. `priority` is `null` when the ticket has no priority and no suggested priority.

## Verifying signatures

Every request includes headers you can use to authenticate that it came from
Risotto and was not tampered with in transit:

| Header              | Description                                                                 |
| ------------------- | --------------------------------------------------------------------------- |
| `Webhook-Id`        | The event `id`. Shared across retries of the same event, for deduplication. |
| `Webhook-Timestamp` | Unix timestamp (seconds) of the delivery attempt.                           |
| `Webhook-Signature` | The signature, formatted as `v1,<base64-encoded HMAC-SHA256>`.              |

To verify a request:

1. **Construct the signed content**

   Concatenate the `Webhook-Id`, `Webhook-Timestamp`, and the raw request body,
   separated by periods: `{id}.{timestamp}.{body}`.

2. **Compute the HMAC**

   Compute an HMAC-SHA256 of that string using your endpoint's signing secret as
   the key, then Base64-encode the result.

3. **Compare signatures**

   Compare your computed value against the Base64 portion of the
   `Webhook-Signature` header (the part after `v1,`) using a constant-time
   comparison. Reject the request if they do not match.

> **Tip:** Also check that `Webhook-Timestamp` is recent (for example, within a few
> minutes of the current time) to protect against replay attacks.

## Retry schedule

Risotto considers a delivery successful only when your endpoint responds with an
HTTP `2xx` status. Each attempt times out after 10 seconds. Non-`2xx`
responses, timeouts, connection errors, and redirects all count as failures.

When an attempt fails, Risotto retries up to 7 times on a fixed backoff
schedule:

| Attempt          | Delay after previous attempt |
| ---------------- | ---------------------------- |
| Initial delivery | —                            |
| Retry 1          | 5 seconds                    |
| Retry 2          | 5 minutes                    |
| Retry 3          | 30 minutes                   |
| Retry 4          | 2 hours                      |
| Retry 5          | 5 hours                      |
| Retry 6          | 10 hours                     |
| Retry 7          | 10 hours                     |

This is 8 attempts in total, spanning roughly a day. If all attempts fail, the
delivery is marked **failed**.

## Auto-disable

If an endpoint fails continuously for **3 days**, Risotto automatically disables
it to stop delivering to an unreachable destination. A single successful (`2xx`)
delivery resets the failure streak, so an endpoint that recovers on its own is
never disabled.

Re-enable a disabled endpoint from **Settings > Developers > Webhooks** in the
Dashboard. A disabled endpoint shows an **Auto-disabled** badge. Turn on the
switch in its **Enabled** column. Re-enabling clears the failure streak and resumes deliveries.

## Failure notifications

When an endpoint is auto-disabled, Risotto notifies your organization's admins
with a **"Webhook endpoint auto-disabled"** warning. The notification appears as
a Dashboard notification and is posted to your organization's
[notifications channel](https://www.tryrisotto.com/docs/dashboard/settings/notifications) if one is configured.
It identifies the affected endpoint and prompts you to re-enable it once the
destination is healthy.

> **Note:** Notifications are sent only when an endpoint is auto-disabled, not on each
> individual failed delivery. Use the [delivery log](#delivery-logs-and-testing)
> to investigate specific failures.

## Delivery logs and testing

Each endpoint keeps a delivery log so you can inspect and troubleshoot
deliveries. To open it, click the actions menu (⋮) on the endpoint row, then
click **Delivery Log**.

- **View deliveries**: See each attempt, its response status, and payload.
  Delivery records are retained for 30 days.
- **Redeliver**: Click the redeliver icon on a delivery to resend a past event
  to the endpoint, for example after fixing an outage on your side.
- **Send Test Event**: Click this button to send a sample event to confirm your endpoint is
  reachable and your signature verification works, without waiting for a real
  event.

Source: https://www.tryrisotto.com/docs/integrations/webhooks
