FileSignal API and webhooks.

Authorization: Bearer fs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl -s "https://filesignal.ca/api/v1/signals?municipality=toronto&category_group=food-hospitality&signal_type=new&has_phone=true&limit=50" \
  -H "Authorization: Bearer $FILESIGNAL_API_KEY"

{
  "data": [
    {
      "id": "6f1c2a7e-0d4b-4a39-9a51-2c8e5b1f0e77",
      "signal_type": "new",
      "detected_at": "2026-10-28T11:16:04Z",
      "effective_date": "2026-10-27",
      "business_name": "Example Noodle House",
      "legal_name": "Example Noodle House Inc.",
      "phone": "(416) 555-0100",
      "address": "123 Example St W",
      "city": "Toronto",
      "postal_code": "M5V 0A1",
      "province": "ON",
      "municipality": "Toronto",
      "category": "Restaurants & bars",
      "category_group": "Food & hospitality",
      "confidence": 0.95,
      "source": "Municipal Licensing & Standards — Business Licences and Permits",
      "source_record_id": "B71-0000000",
      "source_url": "https://open.toronto.ca/dataset/municipal-licensing-and-standards-business-licences-and-permits/"
    }
  ],
  "next_cursor": "eyJkIjoiMjAyNi0xMC0yOFQxMToxNjowNFoiLCJpIjoiNmYxYy4uLiJ9"
}

const BASE = "https://filesignal.ca/api/v1";

async function* allSignals(params) {
  let cursor = null;
  do {
    const qs = new URLSearchParams({ ...params, limit: "200", ...(cursor ? { cursor } : {}) });
    const res = await fetch(`${BASE}/signals?${qs}`, {
      headers: { Authorization: `Bearer ${process.env.FILESIGNAL_API_KEY}` },
    });
    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") ?? 60);
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (!res.ok) {
      const { error } = await res.json();
      throw new Error(`${res.status} ${error.code}: ${error.message}`);
    }
    const body = await res.json();
    yield* body.data;
    cursor = body.next_cursor;
  } while (cursor);
}

for await (const s of allSignals({ signal_type: "new", from: "2026-10-01" })) {
  console.log(s.business_name, s.category, s.city);
}

curl -s "https://filesignal.ca/api/v1/signals/6f1c2a7e-0d4b-4a39-9a51-2c8e5b1f0e77" \
  -H "Authorization: Bearer $FILESIGNAL_API_KEY"

{
  "data": {
    "id": "6f1c2a7e-0d4b-4a39-9a51-2c8e5b1f0e77",
    "signal_type": "new",
    "business_name": "Example Noodle House",
    "...": "all Signal fields",
    "changed_fields": [],
    "field_provenance": {
      "business_name": { "source_field": "Operating Name", "source_record_id": "B71-0000000", "fetched_at": "2026-10-28T11:15:41Z" },
      "phone": { "source_field": "Business Phone", "source_record_id": "B71-0000000", "fetched_at": "2026-10-28T11:15:41Z" }
    }
  }
}

{
  "data": [
    { "slug": "restaurants-bars", "name": "Restaurants & bars", "group_slug": "food-hospitality", "group_name": "Food & hospitality" },
    { "slug": "personal-services", "name": "Salons, spas & personal care", "group_slug": "personal-services", "group_name": "Personal services" }
  ]
}

{
  "data": [
    { "slug": "toronto", "name": "Toronto", "region": "Toronto", "status": "live" },
    { "slug": "mississauga", "name": "Mississauga", "region": "Peel", "status": "building" },
    { "slug": "markham", "name": "Markham", "region": "York", "status": "planned" }
  ]
}

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Content-Type: application/json

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded (120 requests per minute). Retry after 60 seconds." } }

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-FileSignal-Event: signals.created
X-FileSignal-Signature: t=1761650165,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "event": "signals.created",
  "sent_at": "2026-10-28T11:16:05Z",
  "count": 1,
  "data": [ { "id": "6f1c2a7e-…", "signal_type": "new", "business_name": "Example Noodle House", "...": "all Signal fields" } ]
}

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

const SECRET = process.env.FILESIGNAL_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 5 * 60;

export function verifySignature(rawBody, header, secret = SECRET, now = Math.floor(Date.now() / 1000)) {
  if (!header) return false;
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || !parts.v1 || Math.abs(now - t) > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

const app = express();

// Use the raw body: re-serialising parsed JSON changes the bytes and breaks the signature.
app.post("/webhooks/filesignal", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifySignature(raw, req.get("X-FileSignal-Signature"))) return res.status(400).send("bad signature");
  const payload = JSON.parse(raw);
  if (payload.event === "signals.created") {
    for (const s of payload.data) {
      // Upsert on s.id — deliveries can repeat after a retry.
    }
  }
  res.sendStatus(204); // respond 2xx within 10 seconds
});