# Receive and verify webhooks

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.

![Organization Settings, API & MCP, Webhooks tab: the Add webhook form with a name, receiver URL and the event picker grouped by subject (tasks, requests, pull requests), over the list of webhooks.](https://volobox.io/docs/images/admin-webhooks.light.webp)

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

**Node.js (Express)**

```javascript
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);
```

**C# (ASP.NET Core)**

```csharp
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var secret = Encoding.UTF8.GetBytes(app.Configuration["VOLOBOX_WEBHOOK_SECRET"]!); // whsec_...

app.MapPost("/volobox/webhooks", async (HttpRequest request) =>
{
    // Read the exact bytes Volobox signed; do not bind the body to a model first.
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer);
    var body = buffer.ToArray();

    var expected = Encoding.UTF8.GetBytes(
        "sha256=" + Convert.ToHexString(HMACSHA256.HashData(secret, body)).ToLowerInvariant());
    var received = Encoding.UTF8.GetBytes(request.Headers["X-Volobox-Signature-256"].ToString());
    if (!CryptographicOperations.FixedTimeEquals(expected, received))
    {
        return Results.Unauthorized();
    }

    using var json = JsonDocument.Parse(body);
    var eventId = json.RootElement.GetProperty("id").GetString();
    // Your code: skip eventId if you already processed it, and queue the rest of the work.
    return Results.NoContent(); // answer within ten seconds
});

app.Run();
```

**Python (Flask)**

```python
import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

SECRET = os.environ["VOLOBOX_WEBHOOK_SECRET"].encode("utf-8")  # whsec_...
app = Flask(__name__)

def has_valid_signature(raw_body: bytes, header: str | None) -> bool:
    if not header:
        return False
    expected = "sha256=" + hmac.new(SECRET, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected.encode("utf-8"), header.encode("utf-8"))

@app.post("/volobox/webhooks")
def volobox_webhook():
    raw_body = request.get_data()  # the exact bytes Volobox signed
    if not has_valid_signature(raw_body, request.headers.get("X-Volobox-Signature-256")):
        abort(401)

    event = json.loads(raw_body)
    queue_for_processing(event)  # your code: skip it if you already processed event["id"]
    return "", 204  # answer within ten seconds
```

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](/docs/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](/docs/api-overview).

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

| Symptom | Fix |
| --- | --- |
| Your receiver says the signature does not match | Compute 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 timeout | Answer within ten seconds and move the work after the answer. |
| Deliveries fail although your receiver answers | A redirect counts as a failure. Use the final address as the **Receiver URL**. |
| **Receiver URL** is refused when you save | It does not start with `https://`, or it is on a private network. The reason is shown under the field. |
| The webhook shows **Retrying** | Your receiver keeps failing and Volobox waits longer between attempts, up to an hour. A success clears it. |
| The webhook shows **Turned off** | It 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 twice | Expected now and then. Deduplicate on the body's `id`. |
| **Support tickets** is not offered under **Events** | Support is not turned on for the workspace. |
| Docs or Files events from before you added the webhook never arrived | Volobox records those events only while a webhook, a workflow trigger or an app listens for them. |

## Next steps

- [Webhooks](/docs/webhooks): headers, envelope fields, retry schedule and delivery semantics.
- [Event catalog](/docs/events): every event you can choose.
- [API overview](/docs/api-overview): read the details an event points to.
