Verify webhooks

What BrytIO sends

One POST to each webhook subscribed to the event, with a JSON body like this one.

{
  "event": "deal.won",
  "organizationId": "cm2k8x0ab0001qz7h3c9d4e5f",
  "sentAt": "2026-10-22T14:03:11.482Z",
  "data": {
    "deal": {
      "id": "cm2k9a1cd0004qz7hb2e6f7g8",
      "title": "Annual support renewal",
      "value": 18400,
      "stage": "WON"
    }
  },
  "id": "evt_5f2b8c1e9a7d4f3b8e6c2a1d0f9e8b7c",
  "created": "2026-10-22T14:03:11.120Z"
}

New fields can appear, so ignore the ones you don't use. id and created were added after the first four, which kept their names and their order.

Headers

The two legacy headers carry the product's old name. They are still sent, unchanged, so receivers built on them keep working. Use BrytIO-Signature in anything new. Header names aren't case sensitive, and many servers show them in lowercase.

Check the signature

1. Read the body exactly as it arrived, before any JSON parsing. Parsing and writing it out again changes the bytes, and the signature no longer matches.
2. Split BrytIO-Signature at its commas. t is when BrytIO signed the delivery, in Unix seconds. Each v1 is a signature.
3. Compute the HMAC SHA-256 of <t>.<raw body> (the value of t, a period, then the body), keyed with your webhook's signing secret, the whole of it with whsec_ included, as lowercase hex.
4. Compare it with each v1 in constant time, with crypto.timingSafeEqual in Node or hmac.compare_digest in Python. Accept the delivery when any of them matches: more than one can appear.
5. Turn the delivery away when t is more than 5 minutes from your server's clock, either way. A copy someone captured can't be replayed later.

Node

const crypto = require("node:crypto");

// rawBody: the request body exactly as it arrived (a Buffer), before any JSON parsing.
// header: the BrytIO-Signature header. secret: your webhook's signing secret, whsec_ included.
function verifyBrytioWebhook(rawBody, header, secret, toleranceSeconds = 300) {
  const pairs = String(header || "").split(",").map((part) => {
    const [key, ...value] = part.trim().split("=");
    return [key, value.join("=")];
  });
  const timestamp = pairs.find(([key]) => key === "t")?.[1] || "";
  const signatures = pairs.filter(([key]) => key === "v1").map(([, value]) => value);
  if (!/^\d+$/.test(timestamp) || signatures.length === 0) {
    throw new Error("Missing or malformed BrytIO-Signature header");
  }
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
    throw new Error("Timestamp is too old or too far ahead");
  }
  // Compared as the hex text itself, so only the exact 64 lowercase characters match.
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(timestamp + ".").update(rawBody).digest("hex"));
  const valid = signatures.some((signature) => {
    const given = Buffer.from(signature);
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
  if (!valid) throw new Error("Signature does not match");
  return JSON.parse(rawBody.toString("utf8"));
}

// Express: express.raw() keeps the body as it arrived, for this route only.
app.post("/webhooks/crm", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = verifyBrytioWebhook(req.body, req.get("BrytIO-Signature"), process.env.WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send(err.message);
  }
  res.sendStatus(200);
  // Then do the work, once: skip event.id if you have already handled it.
});

Python

import hashlib
import hmac
import json
import time

# raw_body: the request body exactly as it arrived (bytes), before any JSON parsing.
# header: the BrytIO-Signature header. secret: your webhook's signing secret, whsec_ included.
def verify_brytio_webhook(raw_body, header, secret, tolerance_seconds=300):
    pairs = [part.strip().split("=", 1) for part in (header or "").split(",")]
    pairs = [pair for pair in pairs if len(pair) == 2]
    timestamp = next((value for key, value in pairs if key == "t"), "")
    signatures = [value for key, value in pairs if key == "v1"]
    if not (timestamp.isascii() and timestamp.isdigit()) or not signatures:
        raise ValueError("Missing or malformed BrytIO-Signature header")
    # Whole seconds as integers: a t too long for a float is turned away like any stale one.
    if abs(int(time.time()) - int(timestamp)) > tolerance_seconds:
        raise ValueError("Timestamp is too old or too far ahead")
    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest().encode()
    if not any(hmac.compare_digest(expected, signature.encode()) for signature in signatures):
        raise ValueError("Signature does not match")
    return json.loads(raw_body)

# Flask: request.get_data() is the body as it arrived. app is your Flask app.
import os

from flask import request


@app.post("/webhooks/crm")
def crm_webhook():
    try:
        event = verify_brytio_webhook(
            request.get_data(), request.headers.get("BrytIO-Signature"), os.environ["WEBHOOK_SECRET"]
        )
    except ValueError:
        return "", 400
    # Skip event["id"] if you have already handled it, and answer quickly.
    return "", 200

Keep the signing secret on your server, never in a browser or an app. It is shown once, when the webhook is added in Settings > Developers. For a new secret, add the webhook again and then delete the old one: until you do, both get every event with the same event id, so a receiver that skips ids it has seen still handles each event once.

Answer fast and handle each event once

• Answer with any 2xx status as soon as the signature checks out, then do the work. BrytIO waits 8 seconds at most for the answer.

• Keep the ids you've handled and skip one you've seen, using id from the body you checked. The signature covers the body but not the headers, so a copy with a changed BrytIO-Event-Id still checks out. Every webhook that receives an event gets the same id, so two webhooks pointed at one receiver don't do the work twice.

• Events can arrive in any order. Compare created, or read the record through the API, when the order matters.

How delivery works today

• Each webhook gets one attempt per event. Nothing is retried, so a delivery that fails is not sent again.

• A delivery fails when your server doesn't answer within 8 seconds, answers with a status outside 2xx, or can't be reached.

• Redirects aren't followed, except a 307 or 308 to the same host, such as http to https or an added trailing slash, at most twice.

• Deliveries go only to public internet addresses, never to private or internal ones.

• Settings > Developers shows each webhook's latest delivery: the event, the answer's status and when it was sent.

• Webhooks deliver while your workspace is on a plan that includes the API and webhooks: Team and Enterprise.

Events

• A webhook subscribes to any of these in Settings > Developers.

  • deal.created
  • deal.won
  • deal.lost
  • deal.deleted
  • contact.created
  • company.created
  • quote.created
  • quote.accepted
  • invoice.created
  • invoice.paid
  • invoice.overdue

• These are sent only for changes made through the API, never for edits or deletions made in the BrytIO app:

  • deal.updated
  • contact.updated
  • contact.deleted
  • company.updated
  • company.deleted

• Which actions send which events, and from where, is in the table in the Docs.

Call webhook steps in automations

• A Call webhook step in an automation sends BrytIO-Event-Id, a new id for each call, and BrytIO-Event-Type, the event that started the automation. It is not signed, because a step has no signing secret, and its body is the one the step sets.