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.

Current platform guide

These downloadable examples run in your trusted backend. This static site does not receive events, execute jobs or store your credentials.

Connect your own interface and tools

Use the current generated OpenAPI reference and versioned Developer Kit for headless apps, typed clients, webhooks and supported MCP tools. Keep app credentials on a trusted server. Delegated user identity, scopes and action permissions still apply. Sensitive MCP tools require app-level approval; installing an MCP client does not grant write access.

Read the guide

Manage integrations deliberately

Configure connections and credentials for the intended app and organization, verify the connection, then explicitly enable the supported workflow or schedule. Mail delivery, payment processing, Snowflake export and background jobs depend on their configured providers and workers. A queued receipt is not delivery, bank settlement or completed execution.