hooka-relay-node

Server-side Node.js 20.9+ client for Hooka Relay.

npm install hooka-relay-node

import { HookaRelay, HookaError } from "hooka-relay-node";
const relay = new HookaRelay(process.env.HOOKA_API_KEY!);
const event = await relay.sendEvent({
  customerId: "cus_123", type: "order.created", payload: { orderId: "123" }, idempotencyKey: "order-123-created",
});
console.log(event.id);

Use an application key with ingest permission. The customer ID must belong to that application; create customers in the dashboard or customer API before sending. baseUrl, timeoutMs (default 30,000), and fetch are optional constructor settings. HTTP is allowed only for localhost development; redirects are rejected to prevent credential forwarding. The client makes one request, with no implicit retry. On ambiguous network failure, retry with the same explicit idempotencyKey. Omitted keys are generated by the server; resending without a key can create another event.

HookaError exposes status, parsed body, and the raw retryAfter header. Rate limits return 429, oversized requests 413, and schema failures 400 with failures: [{path, message}]. Input limit: 256 KiB / JSON depth 32. Types are generated from the repository's OpenAPI contract.

Verify and queue, then drain

verifyWebhook(rawBody, headers, secret) delegates to the Standard Webhooks reference library. It throws on an invalid signature, changed ID/body, or timestamp outside five minutes. Use the displayed whsec_ secret and raw bytes. During rotation either key verifies the space-separated signatures.

Minimal receiver using only Node's HTTP module. Acknowledge after queue admission; slow processing runs separately. Return 503 when the bounded queue is full so Hooka Relay can retry.

import { createServer } from "node:http";
import { verifyWebhook } from "hooka-relay-node";
const queue = [];
async function processEvent(item) { console.log(item.id, item.payload); }
setInterval(async () => {
  if (draining) return;
  draining = true;
  try {
    for (let item; (item = queue.shift());) {
      try { await processEvent(item); }
      catch (error) { console.error("Move failed item to your dead-letter store", item.id, error); }
    }
  } finally { draining = false; }
}, 25);
let draining = false;
createServer(async (req, res) => {
  if (req.method !== "POST" || req.url !== "/webhook") { res.writeHead(404).end(); return; }
  const chunks = []; let bytes = 0;
  try {
    for await (const chunk of req) {
      bytes += chunk.length;
      if (bytes > 262144) { res.writeHead(413).end(); return; }
      chunks.push(chunk);
    }
    const headers = Object.fromEntries(["webhook-id", "webhook-timestamp", "webhook-signature"].map(k => [k, typeof req.headers[k] === "string" ? req.headers[k] : ""]));
    const payload = verifyWebhook(Buffer.concat(chunks), headers, process.env.HOOKA_SIGNING_SECRET);
    if (queue.length >= 1000) { res.writeHead(503).end(); return; }
    queue.push({ id: headers["webhook-id"], payload });
    res.writeHead(202).end();
  } catch { res.writeHead(400).end(); }
}).listen(8080);

This example's queue is volatile: a process crash loses acknowledged work. For production, durably enqueue before acknowledging (for example, a Postgres inbox table or persistent Redis queue). Atomically deduplicate the verified webhook-id with your business changes. Persist failed processing items for retry/dead-letter handling; logging alone does not recover them.

Event ordering

Ordering is not guaranteed across retries or replay generations. The queue-and-drain example above keeps slow or failing handlers from blocking acknowledgement. It does not restore producer ordering: use per-entity sequence/version checks when your business logic needs that guarantee.

Interactive API reference · Security and migration