Developer reference

Receive events safely.
Wait for background work correctly.

Dependency-free Node.js examples for exact-body HMAC verification, durable event deduplication, fast acknowledgement, bounded polling, and Retry-After.

Download receiver Download job poller

Verify first

Compute HMAC-SHA256 over <timestamp>.<raw-body> before parsing JSON.

Queue once

Use the event UUID as the durable idempotency key, queue it, then return 2xx promptly.

Poll within bounds

Stop on terminal state, honor 429 Retry-After, and enforce a maximum wait.

Webhook receiver

A complete local receiver

The example accepts only POST /webhooks/buildwithhq, limits bodies to 1 MiB, validates the five-minute replay window, atomically stores each event UUID once, and keeps customer payloads out of logs.

Exact raw bytes are verified before JSON parsing.
New events return 202; already accepted events return 200.
Processing is separate and must remain idempotent by event.id.

Download webhook-receiver.mjs →

BWHQ_WEBHOOK_SIGNING_SECRET=... \
BWHQ_WEBHOOK_QUEUE_DIR=./queue \
node webhook-receiver.mjs

# Local endpoint
http://127.0.0.1:8787/webhooks/buildwithhq

const result = await pollAiRebuild({
  saasAppId: process.env.BWHQ_SAAS_APP_ID,
  credential: process.env.BWHQ_USER_TOKEN,
  jobId: receipt.jobId,
  maximumWaitMs: 10 * 60 * 1000,
});

if (result.status === "failed") {
  // Record the safe failure and correlation ID.
}

Background jobs

Poll the route that actually exists

The public pollable job contract today is AI rebuild status: POST /v1/apps/{saasAppId}/ai/rebuilds, followed by GET /v1/apps/{saasAppId}/ai/rebuilds/{jobId}.

The poller recognizes completed, failed, and cancelled, waits between nonterminal states, and uses the server’s required whole-second Retry-After value after a 429.

Download background-job-poller.mjs →

Offline verification

Run all examples without credentials

node --test examples/examples.test.mjs

Download tests

Your endpoint, your data

webhooks.buildwithhq.com publishes reference code and documentation. It does not accept or retain customer webhook deliveries. Deploy the receiver in your trusted backend and give BuildWithHQ that HTTPS destination.