Docs

Developers / Webhooks

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.

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 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, and it cannot be retrieved again after you close the dialog.

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, auto-disable, and delivery log. 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.

Event types

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

Event typeTriggered when
ticket.createdA new ticket is created from any request source.
ticket.escalatedA ticket is escalated to human support.
comment.addedA public comment is added to a ticket. Internal notes do not fire it.
ticket.closedA ticket reaches a final status, with how it closed.
access.requests.completedA request ticket is resolved, with the granted/denied outcome for each app.

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.

FieldDescription
idUnique identifier for the event. Stable across retries — use it to dedupe.
typeThe event type that triggered the delivery.
created_atISO 8601 timestamp of when the event occurred.
dataThe 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:

FieldDescription
ticket_idThe new ticket's identifier.
titleThe ticket's title.
statusThe ticket's current status, such as open.
sourceWhere the ticket originated, such as slack.
requestorThe person who created the ticket, as { email, name }.
priorityThe ticket's priority, as { value, is_suggested }, or null. See Ticket priority.
external_ticket_idThe 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_atISO 8601 timestamp of when the ticket was created.
{
  "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, plus two escalation fields:

FieldDescription
escalated_atISO 8601 timestamp of when the ticket was escalated to human support.
reasonWhy the ticket was escalated, if a reason was provided; otherwise null.
{
  "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:

FieldDescription
contentThe text of the comment.
author_nameThe display name of the author. For a reply from Risotto, the bot name.
author_emailThe email address of the author, or null for a reply from Risotto.
createdISO 8601 timestamp of when the comment was added.
is_internalAlways false. Internal notes do not fire this event.
sourceWhere the comment came from, such as slack, msteams, email, dashboard, api, jira, or risotto.
ticket_idThe ticket the comment was added to, such as IT-123.
departmentThe department of the ticket, as { id, name, ticket_prefix }.
{
  "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.
  • 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.

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:

FieldDescription
closure_stateHow 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.

{
  "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:

FieldDescription
ticket_idThe resolved ticket's identifier.
requestorThe person who made the request, as { email, name }.
completed_atISO 8601 timestamp of when the ticket was resolved.
requestsArray of the individual access requests and their outcomes (below).

Each item in requests describes one user/application request:

FieldDescription
workflow_uuidIdentifier of the request, for correlation. Use this field.
workflow_idDeprecated integer identifier of the request. Use workflow_uuid.
softwareName of the application requested.
statusOutcome: granted, denied, canceled, or escalated.
granteeThe user the access is for, as { email, name }.
reasonReason associated with the outcome, if any.
resolved_atISO 8601 timestamp of when this request was resolved.
expires_atWhen granted access expires, or null for permanent or non-granted access.
granted_by_emailEmail of the granter, set only for manual grants.
access_ruleThe matched access rule, as { rule_id, software_name, app_id, app_name }.
{
  "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. It has two fields:

FieldDescription
valuelow, medium, high, or urgent.
is_suggestedfalse 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:

HeaderDescription
Webhook-IdThe event id. Shared across retries of the same event, for deduplication.
Webhook-TimestampUnix timestamp (seconds) of the delivery attempt.
Webhook-SignatureThe 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.

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:

AttemptDelay after previous attempt
Initial delivery—
Retry 15 seconds
Retry 25 minutes
Retry 330 minutes
Retry 42 hours
Retry 55 hours
Retry 610 hours
Retry 710 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 if one is configured. It identifies the affected endpoint and prompts you to re-enable it once the destination is healthy.

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.

Something wrong or missing? Report an issue · View as Markdown