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

  1. A company owner or admin opens the admin portal and goes to Webhooks.
  2. Enter a name (up to 80 characters), the HTTPS URL that should receive events, and the events to subscribe to.
  3. 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

TypeWhen it firesdata fields
chat.messageA message is sent in a channel, DM, group or room, including file messagesmessageId, userId, userName, content, groupId, spaceId, sentAtUtc
member.joinedA member is added, accepts an invite, or registers into the companyuserId, displayName, email, role
meeting.updatedA calendar meeting is editedid, title, startsAtUtc, endsAtUtc, spaceId, spaceName, zoomJoinUrl, organizerUserId, organizerName, attendees (userId, displayName, email, rsvp)
meeting.cancelledA calendar meeting is cancelledSame as meeting.updated
meeting.endedThe last person leaves a room callsessionId, 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

HeaderValue
X-VO-Signaturesha256= followed by the lowercase hex HMAC-SHA256 of {timestamp}.{rawBody}, keyed with the endpoint secret
X-VO-TimestampUnix seconds used in the signature
X-VO-EventThe event type, for example chat.message
X-VO-DeliveryUnique 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();
});

Retries and delivery

  • Respond with any 2xx status 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 id to 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.