Webhooks
Get an HTTPS callback the moment something happens in your office: a new message, a new member, or a meeting that changes, is cancelled or ends.
Create an endpoint
- A company owner or admin opens the admin portal and goes to Webhooks.
- Enter a name (up to 80 characters), the HTTPS URL that should receive events, and the events to subscribe to.
- Copy the signing secret. It starts with
whsec_and is shown once.
Loopback and private network addresses are rejected as targets. An endpoint can be disabled, which stops new deliveries, or deleted.
Events
| Type | When it fires | data fields |
|---|---|---|
chat.message | A message is sent in a channel, DM, group or room, including file messages | messageId, userId, userName, content, groupId, spaceId, sentAtUtc |
member.joined | A member is added, accepts an invite, or registers into the company | userId, displayName, email, role |
meeting.updated | A calendar meeting is edited | id, title, startsAtUtc, endsAtUtc, spaceId, spaceName, zoomJoinUrl, organizerUserId, organizerName, attendees (userId, displayName, email, rsvp) |
meeting.cancelled | A calendar meeting is cancelled | Same as meeting.updated |
meeting.ended | The last person leaves a room call | sessionId, spaceId, startedAtUtc, endedAtUtc |
Important.
chat.message covers every conversation in the company, including direct messages, so treat the receiving endpoint and its logs as private data.Payload
Each delivery is an HTTPS POST with a JSON envelope:
POST body
{
"id": "0d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
"type": "chat.message",
"companyId": "11111111-2222-4333-8444-555555555555",
"createdAt": "2026-11-20T15:00:00Z",
"data": {
"messageId": "7f8e9d0c-1b2a-4394-8576-a1b2c3d4e5f6",
"userId": "8d4f2a66-1b3c-47e9-b0d2-5c6a7e8f9012",
"userName": "Omar Khan",
"content": "New icons are ready for review",
"groupId": "6f1d2c3b-8a4e-4f7a-9b2c-1d3e5f7a9b0c",
"spaceId": null,
"sentAtUtc": "2026-11-20T15:00:00Z"
}
}Headers
| Header | Value |
|---|---|
X-VO-Signature | sha256= followed by the lowercase hex HMAC-SHA256 of {timestamp}.{rawBody}, keyed with the endpoint secret |
X-VO-Timestamp | Unix seconds used in the signature |
X-VO-Event | The event type, for example chat.message |
X-VO-Delivery | Unique delivery id |
Verify the signature
Compute the HMAC over the exact raw body you received, before parsing it, and compare in constant time.
C#
using System.Security.Cryptography;
using System.Text;
app.MapPost("/collabiro/webhook", async (HttpRequest request) =>
{
var secret = builder.Configuration["Collabiro:WebhookSecret"]!; // whsec_...
using var reader = new StreamReader(request.Body);
var body = await reader.ReadToEndAsync();
var timestamp = request.Headers["X-VO-Timestamp"].ToString();
var signature = request.Headers["X-VO-Signature"].ToString();
// Reject old deliveries to block replays (5 minutes here).
if (!long.TryParse(timestamp, out var unix) ||
Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - unix) > 300)
return Results.Unauthorized();
var hash = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), Encoding.UTF8.GetBytes($"{timestamp}.{body}"));
var expected = "sha256=" + Convert.ToHexString(hash).ToLowerInvariant();
if (!CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(signature)))
return Results.Unauthorized();
// Handle the event (use X-VO-Delivery or the envelope id to ignore duplicates).
return Results.Ok();
});JavaScript
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/collabiro/webhook", express.raw({ type: "application/json" }), (req, res) => {
const body = req.body.toString("utf8");
const ts = req.get("X-VO-Timestamp");
const sig = req.get("X-VO-Signature") ?? "";
const expected = "sha256=" + crypto
.createHmac("sha256", process.env.COLLABIRO_WEBHOOK_SECRET)
.update(`${ts}.${body}`)
.digest("hex");
const ok = sig.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
if (!ok || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
const event = JSON.parse(body);
console.log(event.type, event.data);
res.sendStatus(200);
});Retries and delivery
- Respond with any
2xxstatus to acknowledge a delivery. Anything else, or a network error, counts as a failure. - Failed deliveries are retried with exponential backoff, up to 5 attempts by default.
- The portal shows each endpoint's last delivery time, status, HTTP code and error.
- A retry may deliver the same event twice. Use the envelope
idto ignore duplicates. - Respond quickly and do slow work in the background.
Questions
How do I verify a Collabiro webhook?
Compute HMAC-SHA256 of the X-VO-Timestamp value, a dot and the raw request body, keyed with your whsec_ secret, and compare 'sha256=' plus the lowercase hex digest with the X-VO-Signature header in constant time.
Last updated 20 November 2026. Something missing or wrong? Tell us.