Webhooks

curl -X POST https://mask.pk/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "ws_abc123",
    "url": "https://your-app.com/webhooks/mask",
    "events": ["link.created", "page.published", "conversion.created"]
  }'

{
  "success": true,
  "data": {
    "id": "wh_abc123",
    "url": "https://your-app.com/webhooks/mask",
    "events": ["link.created", "page.published", "conversion.created"],
    "secret": "whsec_...",
    "enabled": true,
    "createdAt": "2026-08-28T14:00:00Z"
  }
}

{
  "event": "link.created",
  "timestamp": "2026-08-28T10:00:00.000Z",
  "data": {
    "id": "lnk_def456",
    "workspaceId": "ws_abc123",
    "slug": "new-campaign",
    "domain": "mask.bz",
    "destinationUrl": "https://example.com/campaign",
    "title": "Q1 campaign"
  }
}

{
  "event": "report.shared",
  "timestamp": "2026-08-28T15:22:10.000Z",
  "data": {
    "workspaceId": "ws_abc123",
    "reportId": "rpt_abc123",
    "title": "March performance",
    "visibility": "TOKEN"
  }
}

import crypto from "crypto";

// MASK signs the timestamp, a full stop, then the raw body -- never the body alone.
function verifyMaskSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    String(header || "").split(",").map((p) => p.split("=", 2))
  );
  const timestamp = parts.t;
  const received = parts.v1;
  if (!timestamp || !received) return false;

  // A signature stays valid forever unless you bound it. Reject stale deliveries.
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > toleranceSeconds) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  const a = Buffer.from(received, "hex");
  const b = Buffer.from(expected, "hex");
  // timingSafeEqual throws on a length mismatch, so compare lengths first.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// Express -- express.raw(), so the bytes MASK signed are the bytes you verify.
app.post("/webhooks/mask", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.headers["x-webhook-signature"];
  if (!verifyMaskSignature(req.body, header, process.env.MASK_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(req.body.toString("utf8"));
  console.log("Received", event.event, "at", event.timestamp);

  // Acknowledge first, process afterwards.
  res.status(200).json({ received: true });
});

import hmac
import hashlib
import time

# MASK signs the timestamp, a full stop, then the raw body -- never the body alone.
def verify_mask_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
    timestamp, received = parts.get("t"), parts.get("v1")
    if not timestamp or not received:
        return False
    if abs(int(time.time()) - int(timestamp)) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        (timestamp + ".").encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(received, expected)

# Flask -- request.data is the raw body, which is what was signed.
@app.route("/webhooks/mask", methods=["POST"])
def handle_webhook():
    header = request.headers.get("X-Webhook-Signature")
    if not verify_mask_signature(request.data, header, WEBHOOK_SECRET):
        return {"error": "Invalid signature"}, 401

    event = request.get_json()
    print("Received", event["event"], "at", event["timestamp"])

    return {"received": True}, 200