Send Freesbe events to your server

An outgoing webhook tells your server when something happens in Freesbe: a new message in #orders, someone joining the workspace, a meeting being booked, a recording that’s ready, someone clocking in. Each event arrives as a signed POST. An owner or admin makes the webhook; you need a server that can take HTTPS requests.

If you’d rather not run a server, use Zapier, Make or n8n.

1. Make the webhook

1. Open Workspace settings → Integrations & apps → Webhooks → Outgoing and click Add outgoing webhook.
2. Give it a name, such as “Ticketing system”, and enter the Payload URL on your server.
3. Leave Channel on All public channels, or pick one channel to only get its events.
4. Tick the events you want and click Create webhook.
5. Copy the Signing secret. It’s only shown once.

There are 30 events, in five groups: messages, channels, people, huddles and meetings, and the punch clock. Workspace-wide events (people, meetings, bookings and the punch clock) only go to webhooks on All public channels.

2. Check each request’s signature

Every request has these headers:

• Freesbe-Event: the event’s name.
• Freesbe-Delivery: an ID for this delivery. Use it to skip one you’ve already handled.
• Freesbe-Signature: t=<unix seconds>,v1=<hex>.

v1 is the HMAC-SHA256 of <t>.<raw body> under the signing secret. In Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  return (
    fresh &&
    v1?.length === expected.length &&
    timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
  );
}

Check the raw body, before parsing the JSON, and turn away requests older than five minutes.

3. Test it

Click Send test on the webhook. Your server gets a webhook.test event. Deliveries on the webhook shows each attempt from the last 14 days and how your server answered.

If something’s wrong

• The signature never matches. You’re signing the parsed and re-serialized JSON instead of the raw body, or using an old secret. Choose ⋯ → Make a new secret if you lost it, and update your server.
• Deliveries keep retrying. Your server answered with a 5xx, 408 or 429, or didn’t answer. Freesbe tries 8 more times, from 30 seconds up to 8 hours apart. Answer with a 2xx once you’ve stored the event.
• Deliveries stop after one try. Any other 4xx answer stops retries. Check your server’s logs for why it refused.
• No events from a private channel. Outgoing webhooks get public channels, or the one channel you picked. For DMs and private channels, use an app whose bot is in them.

See API and webhooks and the API reference for what each event carries.