Webhook API: reliable delivery end-to-end

// Pull from a Hooque consumer queue and Ack/Nack explicitly
// Node 18+ (fetch built-in)
const QUEUE_NEXT_URL =
  process.env.HOOQUE_QUEUE_NEXT_URL ??
  "https://app.hooque.io/queues/cons_webhook_events/next";
const TOKEN = process.env.HOOQUE_TOKEN ?? "hq_tok_replace_me";

const headers = { Authorization: `Bearer ${TOKEN}` };

async function processPayload(payload) {
  // Use a provider event ID if available for idempotency.
  // Example: Stripe uses payload.id (evt_...), GitHub uses headers like X-GitHub-Delivery.
  const eventId = payload?.id ?? null;
  if (eventId) {
    // TODO: enforce idempotency (unique constraint / SETNX / dedupe table)
  }

  // TODO: apply your business logic here
  return { ok: true };
}

while (true) {
  const resp = await fetch(QUEUE_NEXT_URL, { headers });

  if (resp.status === 204) break; // queue is empty
  if (!resp.ok) throw new Error(`Hooque next() failed: ${resp.status}`);

  const payload = await resp.json();
  const meta = JSON.parse(resp.headers.get("X-Hooque-Meta") ?? "{}");

  try {
    await processPayload(payload);
    await fetch(meta.ackUrl, { method: "POST", headers });
  } catch (err) {
    await fetch(meta.nackUrl, {
      method: "POST",
      headers: { ...headers, "Content-Type": "application/json" },
      body: JSON.stringify({ reason: String(err) }),
    });
  }
}

# Pull from a Hooque consumer queue and Ack/Nack explicitly
import json
import os
import requests

QUEUE_NEXT_URL = os.getenv(
    "HOOQUE_QUEUE_NEXT_URL",
    "https://app.hooque.io/queues/cons_webhook_events/next",
)
TOKEN = os.getenv("HOOQUE_TOKEN", "hq_tok_replace_me")
headers = {"Authorization": f"Bearer {TOKEN}"}


def process_payload(payload: dict) -> None:
    event_id = payload.get("id")  # use provider event ID where possible
    if event_id:
        # TODO: enforce idempotency (DB unique constraint / Redis SETNX / dedupe store)
        pass

    # TODO: apply your business logic here
    return None


while True:
    resp = requests.get(QUEUE_NEXT_URL, headers=headers, timeout=30)

    if resp.status_code == 204:
        break
    if resp.status_code >= 400:
        raise RuntimeError(f"Hooque next() failed: {resp.status_code} {resp.text}")

    payload = resp.json()
    meta = json.loads(resp.headers.get("X-Hooque-Meta", "{}"))

    try:
        process_payload(payload)
        requests.post(meta["ackUrl"], headers=headers, timeout=30)
    except Exception as err:
        requests.post(
            meta["nackUrl"],
            headers={**headers, "Content-Type": "application/json"},
            json={"reason": str(err)},
            timeout=30,
        )