Webhooks (callback_url)

POST {callback_url}
Content-Type: application/json
X-Awaithumans-Signature: sha256=<hex-digest>
X-Awaithumans-Task-Id: tsk_4f8a2c1e9b...

{
  "task_id": "tsk_4f8a2c1e9b...",
  "idempotency_key": "refund:order-12345",
  "status": "completed",
  "response": {"approved": true, "notes": "Duplicate charge confirmed."},
  "completed_at": "2026-05-12T08:05:23.456Z",
  "timed_out_at": null,
  "completed_by_email": "alice@acme.com",
  "completed_via_channel": "dashboard",
  "verification_attempt": 1
}

import json
from fastapi import FastAPI, HTTPException, Request
from awaithumans.utils.webhook_signing import verify_signature

app = FastAPI()


@app.post("/awaithumans/callback")
async def callback(request: Request):
    body = await request.body()
    sig = request.headers.get("x-awaithumans-signature")

    if not verify_signature(body=body, signature=sig):
        raise HTTPException(401, "bad signature")

    payload = json.loads(body)
    # ... do work, return 2xx ...
    return {"ok": True}

// raw-body.ts
import type { IncomingMessage } from "node:http";

// HMAC verification needs the exact bytes the awaithumans server hashed
// — any framework body-parser that re-serializes JSON will silently
// break the signature. Read once, verify, then parse.
export function readRawBody(req: IncomingMessage): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    req.on("data", (c: Buffer) => chunks.push(c));
    req.on("end", () => resolve(Buffer.concat(chunks)));
    req.on("error", reject);
  });
}

// Temporal — verify + signal a workflow.
import express from "express";
import { Client } from "@temporalio/client";
import { dispatchSignal } from "awaithumans/temporal";

import { readRawBody } from "./raw-body";

const app = express();
const temporalClient = await Client.connect({ address: "localhost:7233" });

app.post("/awaithumans/callback", async (req, res) => {
  const body = await readRawBody(req);
  try {
    await dispatchSignal({
      temporalClient,
      workflowId: req.query.wf as string,
      body,
      signatureHeader: req.headers["x-awaithumans-signature"] as string,
      payloadKey: process.env.AWAITHUMANS_PAYLOAD_KEY!,
    });
    res.json({ ok: true });
  } catch (e) {
    res.status(401).json({ error: String(e) });
  }
});

app.listen(8765);

// LangGraph — verify + resume a graph.
import express from "express";
import { createWebhookHandler } from "awaithumans/langgraph";

import { graph } from "./graph";           // your compiled StateGraph
import { readRawBody } from "./raw-body";

const app = express();
const handler = createWebhookHandler({
  graph,
  payloadKey: process.env.AWAITHUMANS_PAYLOAD_KEY!,
});

app.post("/awaithumans/callback", async (req, res) => {
  const body = await readRawBody(req);
  await handler({
    body,
    signatureHeader: req.headers["x-awaithumans-signature"] as string,
  });
  res.json({ ok: true });
});

app.listen(8765);

HKDF-SHA256(
  ikm  = base64-decode(PAYLOAD_KEY),  # 32 raw bytes
  salt = b"awaithumans-webhook-v1",
  info = b"v1",
  length = 32,
)