Webhooks

X-Institflow-Signature: t=1740906000,v1=5257a869e7bfc...
X-Institflow-Timestamp: 1740906000
X-Institflow-Event: invoice.issued
X-Institflow-Delivery: 0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b

import crypto from 'node:crypto';

function verifyInstitflowSignature(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
// The header is a comma-separated list and MAY carry several v1= values (one per live secret
// during a secret rotation), so never collapse it into an object keyed by field name.
const fields = signatureHeader.split(',').map((part) => part.trim());
const timestamp = Number(fields.find((part) => part.startsWith('t='))?.slice(2));
if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) {
  throw new Error('Signature timestamp outside tolerance — possible replay.');
}
const expected = crypto
  .createHmac('sha256', secret)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');
const expectedBuf = Buffer.from(expected);
const ok = fields
  .filter((part) => part.startsWith('v1='))
  .some((part) => {
    const actual = Buffer.from(part.slice(3));
    return actual.length === expectedBuf.length && crypto.timingSafeEqual(expectedBuf, actual);
  });
if (!ok) {
  throw new Error('Signature mismatch.');
}
}

// Express/Fastify: read the RAW body (before JSON parsing) — the signature is computed over the
// exact bytes Institflow sent, not over a re-serialized object.
app.post('/webhooks/institflow', express.raw({ type: 'application/json' }), (req, res) => {
verifyInstitflowSignature(req.body.toString('utf8'), req.header('X-Institflow-Signature'), process.env.INSTITFLOW_WEBHOOK_SECRET);
const event = JSON.parse(req.body);
// ... handle event.type / event.data
res.sendStatus(200);
});

import hashlib
import hmac
import time

def verify_institflow_signature(raw_body: bytes, signature_header: str, secret: str, tolerance_seconds: int = 300) -> None:
  # The header is a comma-separated list and MAY carry several "v1=" values (one per live
  # secret during a secret rotation), so never collapse it into a dict keyed by field name.
  fields = [part.strip() for part in signature_header.split(",")]
  timestamp = int(next(part[2:] for part in fields if part.startswith("t=")))
  if abs(time.time() - timestamp) > tolerance_seconds:
      raise ValueError("Signature timestamp outside tolerance — possible replay.")
  payload = f"{timestamp}.".encode() + raw_body
  expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
  signatures = [part[3:] for part in fields if part.startswith("v1=")]
  if not any(hmac.compare_digest(expected, candidate) for candidate in signatures):
      raise ValueError("Signature mismatch.")

# Flask: request.get_data() returns the raw, unparsed bytes.
@app.post("/webhooks/institflow")
def institflow_webhook():
  verify_institflow_signature(request.get_data(), request.headers["X-Institflow-Signature"], os.environ["INSTITFLOW_WEBHOOK_SECRET"])
  event = request.get_json()
  # ... handle event["type"] / event["data"]
  return "", 200