Developers

Guide

Receive and verify webhooks

Add a Volobox webhook, verify each delivery's HMAC-SHA256 signature in Node.js, C# or Python, answer fast, and deduplicate events.

At the end of this guide a webhook in Volobox sends the events you chose to an HTTPS endpoint you run, and your endpoint checks that each delivery really comes from Volobox before it acts on it. Adding a webhook needs the Manage API and MCP clients and webhooks permission; the receiver is your own code.

Before you begin

  • The Manage API and MCP clients and webhooks permission in your workspace.
  • An HTTPS address reachable from the internet where your receiver will run. Volobox refuses addresses on a private network, such as localhost, 10.x or 192.168.x.
  • Node.js with Express, .NET 8 or later with ASP.NET Core, or Python 3.10 or later with Flask, to follow one of the examples.

Add a webhook

  1. In Volobox, open Admin at the bottom of the left activity rail, then Settings, open API & MCP, and choose Webhooks.
  2. Click Add webhook.
  3. Enter a Name and the Receiver URL. It must start with https://.
  4. Under Events, keep All events to receive everything that may leave the workspace, including events Volobox adds later. Or clear it and tick whole groups, such as Tasks, or single events, such as Pull request merged. Under Apps, tick an app to receive the events it announces.
  5. If the events include Alerts, choose a Minimum alert severity. It starts at Warning.
  6. To narrow the webhook to some projects, repositories or support desks, tick Only from selected places under Where from and tick the places.
  7. Leave the signing secret to Volobox, or tick Use my own signing secret and type one: 24 to 256 characters, at least 8 of them different, with no spaces at either end.
  8. Click Add webhook. A generated secret appears in the next dialog. It starts with whsec_.

Warning: The signing secret is shown once

Copy a generated secret before you close the dialog; it is not shown again. A secret you typed yourself is not shown at all. Store it where your receiver reads its configuration, never in source control.

Adding a webhook in Organization Settings, API & MCP: a name, the receiver URL, and the events to send, grouped by subject.

Verify the signature

Every delivery carries X-Volobox-Signature-256: sha256= followed by the lowercase hex HMAC-SHA256 of the raw request body, keyed with the whole signing secret (whsec_ included). Your receiver computes the same value over the bytes it received and compares the two in constant time.

Warning: Verify before you parse

Compute the signature over the exact bytes of the body, before any JSON parsing. A body that was parsed and serialized again does not match, even when it holds the same data. Refuse a delivery whose signature does not match.

Each example below reads the secret from VOLOBOX_WEBHOOK_SECRET, accepts deliveries at /volobox/webhooks, answers 401 to a bad signature and 204 to a good one:

import crypto from "node:crypto";
import express from "express";

const secret = process.env.VOLOBOX_WEBHOOK_SECRET; // whsec_...
const app = express();

function hasValidSignature(rawBody, header) {
  if (typeof header !== "string") return false;
  const expected = Buffer.from(
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex"),
  );
  const received = Buffer.from(header);
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

// express.raw keeps the exact bytes Volobox signed; do not put express.json() in front of this route.
app.post("/volobox/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  if (!hasValidSignature(req.body, req.get("X-Volobox-Signature-256"))) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString("utf8"));
  res.sendStatus(204); // answer first, within ten seconds

  queueForProcessing(event); // your code: skip it if you already processed event.id
});

app.listen(3000);

The comparison is constant time in each language: crypto.timingSafeEqual in Node.js (after a length check, since it throws on buffers of different lengths), CryptographicOperations.FixedTimeEquals in C#, and hmac.compare_digest in Python. Do not compare signatures with ==.

Answer fast, process later

Answer with any 2xx status within ten seconds. A slower answer, a status outside 2xx and a redirect all count as a failure, and Volobox tries the delivery again: after 15 seconds, 1 minute, 5 minutes, 15 minutes and 1 hour, up to six attempts in all. Put the event on a queue, answer, and do the slow work afterwards.

After 15 failures in a row Volobox turns the webhook off. The full schedule is in Webhooks.

Deduplicate on the event id

An event can arrive more than once: a retry after your receiver timed out, or a delivery an administrator sent again. Every copy has the same body id. Keep the ids you processed and skip one you have seen.

  • Deduplicate on the body's id, not on X-Volobox-Delivery: a delivery sent again has a new delivery id.
  • Do not rely on arrival order. Sort by occurredAt when order matters.
  • The body carries ids, states and labels, never a message or a description. Read the rest through the API.

Send a test event

In the webhook's ⋯ menu, choose Send test event. Volobox sends a ping at once, signed like any delivery:

JSON
{
  "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" }
}

A ping is not a catalog event and is not retried. Verify it like any delivery, answer 2xx, and skip your processing when event is ping.

Check that it works

  1. Send a test event. Your receiver answers 204.
  2. Click Deliveries on the webhook. The ping is at the top, newest first. Open it to see the request headers and body, the response status and the first part of your response body.
  3. Trigger a real event you selected, such as closing a task in a project the webhook covers. A new delivery appears with its event key, such as task.closed, and your receiver processes it once.

Troubleshooting

SymptomFix
Your receiver says the signature does not matchCompute the HMAC over the raw bytes, not a re-serialized body. Use the whole secret, whsec_ included, with no added spaces or line breaks. If someone used Replace signing secret, the old secret stopped at once: put the new one on the receiver.
Deliveries fail with a timeoutAnswer within ten seconds and move the work after the answer.
Deliveries fail although your receiver answersA redirect counts as a failure. Use the final address as the Receiver URL.
Receiver URL is refused when you saveIt does not start with https://, or it is on a private network. The reason is shown under the field.
The webhook shows RetryingYour receiver keeps failing and Volobox waits longer between attempts, up to an hour. A success clears it.
The webhook shows Turned offIt failed 15 times in a row. Fix the receiver, then open Edit and switch On back on; that clears the failure count.
A delivery shows Skipped (hourly limit)The webhook reached its delivery limit for the hour. Use Send again on the delivery once the burst has passed.
The same event arrives twiceExpected now and then. Deduplicate on the body's id.
Support tickets is not offered under EventsSupport is not turned on for the workspace.
Docs or Files events from before you added the webhook never arrivedVolobox records those events only while a webhook, a workflow trigger or an app listens for them.

Next steps

  • Webhooks: headers, envelope fields, retry schedule and delivery semantics.
  • Event catalog: every event you can choose.
  • API overview: read the details an event points to.