Webhooks

​

Subscribable tables

​

The payload

{
  "type": "UPDATE",
  "table": "salesOrder",
  "companyId": "abc123",
  "record": { "id": "...", "salesOrderId": "SO000042", "status": "To Ship and Invoice" }
}

​

Configuration

• Name: a label, unique within your company.
• Table: the one table to watch.
• URL: where the POST is sent; must be an http or https URL that resolves to a public address. Alforse refuses to deliver to loopback, private-network, link-local and cloud metadata addresses.
• Triggers: any of insert, update, delete (at least one).
• Active: webhooks are on by default; switch off to pause delivery.

​

Delivery & reliability

• Handle duplicates. A request can be retried after your service has processed it. De-duplicate on the event id header, not type and record.id, because separate changes to the same record share the latter values.
• Reconcile after outages. After retries are exhausted, Alforse drops the change. Query the API when complete event processing is required.

​

Verifying deliveries

1. Read the raw body before you parse it. Parsing and re-serialising JSON changes the bytes.
2. Compute the HMAC and compare it with the value after v1= in constant time.
3. Reject a timestamp more than five minutes from your clock, so a captured request cannot be replayed. Each retry is signed again with a new timestamp.

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

export function verifyAlforseSignature(
  rawBody: string,
  signatureHeader: string,
  timestampHeader: string,
  secret: string,
  toleranceSeconds = 300
) {
  const timestamp = Number(timestampHeader);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const received = signatureHeader.replace(/^v1=/, "");
  return (
    received.length === expected.length &&
    timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}

​

Related