Webhooks

Verify the signature

Anyone who knows your URL can send requests to it. Always check the signature before trusting the content:

1. Read the X-BMC-Webhook-Signature header and split out t (Unix seconds) and sha256.
2. Reject the delivery if t is more than 300 seconds away from your clock. This way a captured delivery cannot be replayed later.
3. Compute an HMAC-SHA256 with your full secret (whsec_…) as the key over the text {t}.{body}, where the body is the exact bytes received, without re-serialising the JSON.
4. Compare with sha256 in constant time.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.BMC_WEBHOOK_SECRET; // whsec_…
const TOLERANCE = 300; // seconds

app.post("/webhooks/bmc", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-BMC-Webhook-Signature") ?? "";
  const parts = Object.fromEntries(
    header.split(",").map((kv) => {
      const i = kv.indexOf("=");
      return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()];
    }),
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > TOLERANCE) {
    return res.sendStatus(400);
  }

  // req.body is a Buffer with the exact bytes received
  const expected = crypto.createHmac("sha256", SECRET).update(`${t}.`).update(req.body).digest("hex");
  const received = parts.sha256 ?? "";
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
  if (!valid) return res.sendStatus(400);

  const event = JSON.parse(req.body.toString("utf8"));
  const eventId = req.get("X-BMC-Webhook-Id");
  // 1. If you already processed eventId, answer 200 and do nothing.
  // 2. Otherwise store eventId and queue the work.
  res.sendStatus(200);
});

import hashlib
import hmac
import os
import time

from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["BMC_WEBHOOK_SECRET"]  # whsec_…
TOLERANCE = 300  # seconds


def verify(payload: bytes, header: str) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        t, received = int(parts["t"]), parts["sha256"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > TOLERANCE:
        return False
    expected = hmac.new(SECRET.encode(), f"{t}.".encode() + payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, received)


@app.post("/webhooks/bmc")
def bmc_webhook():
    payload = request.get_data()  # exact bytes, before parsing
    if not verify(payload, request.headers.get("X-BMC-Webhook-Signature", "")):
        return "", 400
    event_id = request.headers["X-BMC-Webhook-Id"]
    # 1. If you already processed event_id, answer 200 and do nothing.
    # 2. Otherwise store event_id and queue the work.
    return "", 200

Expected response and retries

• Answer with any 2xx status to confirm receipt. Be quick: BMC waits 10 seconds at most. If the work is long, store the event, answer and process it afterwards.
• Any other response counts as a failure, including redirects: BMC does not follow them. Not answering in time or failing to connect is also a failure.
• After a failure BMC retries with increasing waits: 1 min, 5 min, 30 min, 2 h, 12 h. That is 6 attempts in total, counting the first. After all of them the delivery is marked as failed.
• Deliveries and their status are shown under Developers › Webhooks and in GET /webhooks/subscriptions/{id}/deliveries. A failed delivery can be resent by hand.

Idempotency

Because of retries, your server may receive the same event more than once. X-BMC-Webhook-Id (and the id field of the body) is the same on every attempt and resend of the event: store it when you process the event and, if it arrives again, answer 200 without repeating the work. X-BMC-Webhook-Delivery changes on each delivery and is useful to trace it in the log.

Arrival order is not guaranteed. If order matters, compare occurred_at or request the current state of the resource from the API.

Testing and secret rotation

• Send a test. From the client area or with POST /webhooks/subscriptions/{id}/test a webhook.test event is sent with a single attempt and the result is shown. It is not a subscribable event.
• Rotate the secret. It generates a new one; the previous one stops working. Update your server with the new value, and do it whenever you suspect the secret has been exposed.
• Pause. A deactivated subscription receives no events.

Event catalogue

Each event requires the read permission of the resource it refers to, the same one the API route that returns it asks for. Permission names are in the permissions catalogue. A subscription can only include the events whose permission the token holds.