Temporal

┌──────────────────────────┐  POST /api/tasks   ┌──────────────────────┐
│ Temporal worker          │ ──────────────────► awaithumans server     │
│  ─ workflow await_human()│                    │                      │
│    parks                 │                    │  notify human ──►    │
│                          │   webhook (signed) │  human completes ──► │
│                          │ ◄──────────────────│                      │
└─────┬────────────────────┘                    └──────────────────────┘
      │ Temporal signal
      │ (via dispatch_signal)
┌─────▼────────────────┐
│ FastAPI receiver     │
│ (your web server)    │
└──────────────────────┘

pip install "awaithumans[temporal]"

import os
from datetime import timedelta

from pydantic import BaseModel
from temporalio import workflow

with workflow.unsafe.imports_passed_through():
    from awaithumans.adapters.temporal import await_human


class RefundPayload(BaseModel):
    amount_usd: int
    customer_id: str


class RefundDecision(BaseModel):
    approved: bool
    notes: str = ""


# Defined in the "Constructing callback_url" section below.
def callback_url_for_workflow(workflow_id: str) -> str:
    base = os.environ.get("AWAITHUMANS_CALLBACK_BASE", "http://localhost:8765")
    return f"{base.rstrip('/')}/awaithumans/callback?wf={workflow_id}"


# Your real refund implementation — registered as a Temporal activity.
@workflow.defn
class RefundWorkflow:
    @workflow.run
    async def run(self, amount: int, customer_id: str) -> dict:
        decision = await await_human(
            task=f"Approve ${amount} refund for {customer_id}?",
            payload_schema=RefundPayload,
            payload=RefundPayload(amount_usd=amount, customer_id=customer_id),
            response_schema=RefundDecision,
            timeout_seconds=15 * 60,
            callback_url=callback_url_for_workflow(workflow.info().workflow_id),
            server_url="http://localhost:3001",
            api_key=os.environ.get("AWAITHUMANS_ADMIN_API_TOKEN"),
        )

        if not decision.approved:
            return {"refund_id": None, "outcome": "rejected"}

        refund_id = await workflow.execute_activity(
            "process_refund",
            args=[amount, customer_id],
            start_to_close_timeout=timedelta(seconds=30),
        )
        return {"refund_id": refund_id, "outcome": "approved"}

# callback_server.py — runs alongside your Temporal worker, separate process
from contextlib import asynccontextmanager
from fastapi import FastAPI, HTTPException, Request
from temporalio.client import Client

from awaithumans.adapters.temporal import dispatch_signal

_client: Client | None = None


@asynccontextmanager
async def lifespan(_app):
    global _client
    _client = await Client.connect("localhost:7233")
    yield


app = FastAPI(lifespan=lifespan)


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

    try:
        await dispatch_signal(
            temporal_client=_client,
            workflow_id=wf,
            body=body,
            signature_header=sig,
        )
    except PermissionError:
        raise HTTPException(401, "bad signature")
    except ValueError as exc:
        raise HTTPException(400, str(exc))

    return {"ok": True}

import os


def callback_url_for_workflow(workflow_id: str) -> str:
    base = os.environ.get("AWAITHUMANS_CALLBACK_BASE", "http://localhost:8765")
    return f"{base.rstrip('/')}/awaithumans/callback?wf={workflow_id}"

ngrok http 8765
export AWAITHUMANS_CALLBACK_BASE=https://<your-ngrok-id>.ngrok.io