# Webhooks

This page is the contract of a webhook delivery: the request Volobox sends, the body's fields, how it is signed, and when it is retried. Which events exist is in the [event catalog](/docs/events); how to set up a receiver is in [Receive and verify webhooks](/docs/receive-webhooks).

## The request

Every delivery is an HTTPS `POST` to the webhook's **Receiver URL** with a JSON body and these headers:

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json; charset=utf-8` |
| `User-Agent` | `Volobox-Webhooks/1.0` |
| `X-Volobox-Event` | The event key, such as `task.closed`, or `ping` for a test event. |
| `X-Volobox-Delivery` | The delivery's own id. A delivery sent again with **Send again** has a new one. |
| `X-Volobox-Signature-256` | `sha256=` followed by the lowercase hex HMAC-SHA256 of the raw body under the webhook's signing secret. |

The **Receiver URL** starts with `https://` and is reachable from the internet. An address on a private network (`localhost`, `10.x`, `192.168.x` and the like) is refused when the webhook is saved, and a host name that leads to one fails every delivery.

## The body

The body is the event's envelope:

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | uuid | The event's id. The same on every attempt and on a delivery sent again. Deduplicate on it. |
| `event` | string | The event key, the same as `X-Volobox-Event`. An event an app announces is named by the app and itself: `app.{appKey}.{event}`, such as `app.orders.order.placed`. |
| `occurredAt` | string | When the event happened, in UTC: `yyyy-MM-ddTHH:mm:ss.fffZ`. |
| `actor.userId` | uuid or null | The person who did it. |
| `actor.agentId` | uuid or null | The agent that did it. |
| `subject.kind` | string | What the event is about, such as `task` or `pull_request`. |
| `subject.id` | uuid | The subject's id. |
| `subject.label` | string or null | A label for the subject, such as a task's title. |
| `subject.number` | integer or null | The subject's number, when it has one (a task's number in its project). |
| `scope.projectId` | uuid or null | The project it happened in. |
| `scope.repositoryId` | uuid or null | The repository it happened in. |
| `scope.supportDeskId` | uuid or null | The support desk it happened in. |
| `scope.appId` | uuid or null | The app it happened in. |
| `data` | object | The event's own fields. They differ by event. |
| `causation.workflowRunId` | uuid or null | The workflow run that caused it. |
| `causation.agentRunId` | uuid or null | The agent run that caused it. |
| `causation.batchId` | uuid or null | Shared by every event of one bulk change, which is still one event per item. |
| `causation.batchSize` | integer or null | How many items that bulk change covers. |
| `webhook.id` | uuid | The webhook this delivery is for. |

An example, with `data` shortened to a few of its fields:

```json title="task.closed"
{
  "id": "6f0d9c2a-3b4e-4f51-9a7c-2d8e1f0b3c45",
  "event": "task.closed",
  "occurredAt": "2026-11-14T09:30:12.345Z",
  "actor": {
    "userId": "1c2b3a4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",
    "agentId": null
  },
  "subject": {
    "kind": "task",
    "id": "9a8b7c6d-5e4f-4321-8765-0fedcba98765",
    "label": "Update the onboarding checklist",
    "number": 42
  },
  "scope": {
    "projectId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "repositoryId": null,
    "supportDeskId": null,
    "appId": null
  },
  "data": {
    "projectId": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "workItemId": "9a8b7c6d-5e4f-4321-8765-0fedcba98765",
    "number": 42,
    "status": "Closed",
    "previousStatus": "Open",
    "closeReason": "Completed"
  },
  "causation": {
    "workflowRunId": null,
    "agentRunId": null,
    "batchId": null,
    "batchSize": null
  },
  "webhook": {
    "id": "4d5e6f7a-8b9c-4d0e-a1f2-3b4c5d6e7f80"
  }
}
```

### What the body never carries

A delivery carries ids, states and labels, never a message, a comment's text or a description body. Read those through the [API](/docs/api-overview) when you need them. Some labels are replaced before they leave the workspace:

- A **Mail** alert is sent as "A shared mailbox needs attention", since its title names a shared mailbox.
- An app's or a workflow's alert is sent as "An app raised an alert" or "A workflow raised an alert", and its `key` is replaced by a stand-in of 16 hexadecimal characters that is the same for every event of that alert.
- A Docs page whose access is restricted is sent without its title.

Messages, meetings and personal alerts are never sent at all.

## The ping

**Send test event** in the webhook's **⋯** menu sends a `ping` at once, signed like any delivery. It is no catalog event and is not retried:

```json title="ping"
{
  "id": "0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
  "event": "ping",
  "occurredAt": "2026-11-14T09:28:00.000Z",
  "data": { "message": "Volobox can reach this webhook." },
  "webhook": { "id": "4d5e6f7a-8b9c-4d0e-a1f2-3b4c5d6e7f80" }
}
```

## The signature

`X-Volobox-Signature-256` is computed as:

```text
"sha256=" + lowercase_hex( HMAC-SHA256( key = UTF-8 bytes of the signing secret,
                                        message = the raw request body bytes ) )
```

- **The key** is the whole signing secret exactly as Volobox showed it, `whsec_` prefix included. A secret an administrator typed with **Use my own signing secret** (24 to 256 characters) is used exactly as typed.
- **The message** is the body bytes as they arrived. Compute the HMAC before you parse the JSON; a parsed and re-serialized body does not match.
- **Compare** your result with the header in constant time.
- **Every attempt** of a delivery sends the same bytes. A delivery is signed with the secret in force when it is sent, so after **Replace signing secret** the old secret stops verifying at once. With **Use my own signing secret**, set the new secret on your receiver first.

> **Warning:** Verify the signature before you parse or act on the body, and refuse a delivery whose signature does not match. Anyone who knows your receiver's address can send it a request.

## Responses and retries

Answer with any `2xx` status within 10 seconds. Anything else counts as a failure: no answer, a timeout, a status that is not `2xx`, and a redirect, which is not followed.

A failed delivery is tried again on this schedule, up to six attempts in all:

| Attempt | When |
| --- | --- |
| 1 | When the event happens |
| 2 | 15 seconds after attempt 1 failed |
| 3 | 1 minute after attempt 2 failed |
| 4 | 5 minutes after attempt 3 failed |
| 5 | 15 minutes after attempt 4 failed |
| 6 | 1 hour after attempt 5 failed |

While a receiver keeps failing, the webhook shows **Retrying** and pauses all its deliveries for longer between attempts, up to an hour. A success clears it.

After **15 failures in a row**, Volobox turns the webhook off, shows **Turned off**, and raises a **Warning** alert for the person who added it and for the **Webhooks** alert recipients. Turning the webhook on again clears its failure count.

## Delivery semantics

- **At least once.** An event can arrive more than once. Keep the `id` of the events you processed and skip a repeat. Do not deduplicate on `X-Volobox-Delivery`: a delivery sent again has a new one.
- **No order.** Deliveries can arrive in a different order than the events happened. Use `occurredAt`.
- **Sent again on request.** **Send again** on a finished delivery in the **Deliveries** log queues the same body once more, under a new delivery id.
- **Within limits.** A webhook sends within per-webhook limits. A delivery over them shows **Skipped (hourly limit)** in the log; use **Send again** once the burst has passed.
- **Covered when sent.** If a webhook is narrowed or its events change while deliveries wait, the ones it no longer covers are not sent and show as failed with the reason.
- **Anyone at the receiver sees it.** A webhook does not follow who may see a private project: whoever holds the receiver sees every event the webhook selects.

## Related

- [Receive and verify webhooks](/docs/receive-webhooks)
- [Event catalog](/docs/events)
- [API overview](/docs/api-overview)
- [API, MCP and webhooks](/docs/api-and-mcp)
