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
Open the Webhooks settings
In the Dashboard, go to Settings > Developers > Webhooks.
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.
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.
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
idis the same at every endpoint that gets the event.
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. |
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 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. |
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. |
{
"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:
| 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. |
{
"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 }. |
{
"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
sourceset torisottoandauthor_emailset tonull. - 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:
| 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.
{
"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 }. |
{
"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:
| 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:
Construct the signed content
Concatenate the
Webhook-Id,Webhook-Timestamp, and the raw request body, separated by periods:{id}.{timestamp}.{body}.Compute the HMAC
Compute an HMAC-SHA256 of that string using your endpoint's signing secret as the key, then Base64-encode the result.
Compare signatures
Compare your computed value against the Base64 portion of the
Webhook-Signatureheader (the part afterv1,) 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:
| 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 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