MCP and events
ReferenceWebhooks
What a Volobox webhook delivery contains: headers, body envelope, ping, signature, retry schedule and delivery semantics.
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; how to set up a receiver is in Receive and verify 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:
{
"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 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
keyis 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:
{
"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:
"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
idof the events you processed and skip a repeat. Do not deduplicate onX-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.