MCP and events

Reference

Webhooks

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:

HeaderValue
Content-Typeapplication/json; charset=utf-8
User-AgentVolobox-Webhooks/1.0
X-Volobox-EventThe event key, such as task.closed, or ping for a test event.
X-Volobox-DeliveryThe delivery's own id. A delivery sent again with Send again has a new one.
X-Volobox-Signature-256sha256= 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:

FieldTypeMeaning
iduuidThe event's id. The same on every attempt and on a delivery sent again. Deduplicate on it.
eventstringThe 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.
occurredAtstringWhen the event happened, in UTC: yyyy-MM-ddTHH:mm:ss.fffZ.
actor.userIduuid or nullThe person who did it.
actor.agentIduuid or nullThe agent that did it.
subject.kindstringWhat the event is about, such as task or pull_request.
subject.iduuidThe subject's id.
subject.labelstring or nullA label for the subject, such as a task's title.
subject.numberinteger or nullThe subject's number, when it has one (a task's number in its project).
scope.projectIduuid or nullThe project it happened in.
scope.repositoryIduuid or nullThe repository it happened in.
scope.supportDeskIduuid or nullThe support desk it happened in.
scope.appIduuid or nullThe app it happened in.
dataobjectThe event's own fields. They differ by event.
causation.workflowRunIduuid or nullThe workflow run that caused it.
causation.agentRunIduuid or nullThe agent run that caused it.
causation.batchIduuid or nullShared by every event of one bulk change, which is still one event per item.
causation.batchSizeinteger or nullHow many items that bulk change covers.
webhook.iduuidThe webhook this delivery is for.

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

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

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:

AttemptWhen
1When the event happens
215 seconds after attempt 1 failed
31 minute after attempt 2 failed
45 minutes after attempt 3 failed
515 minutes after attempt 4 failed
61 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.