aiactradar-examples

# aiactradar-examples

Reference webhook receivers for [AI Act Radar](https://aiactradar.com).
Each subdirectory is a self-contained, runnable example for one platform.

## What every receiver does

1. Reads the **raw** request body (signature is over the bytes, not the parsed JSON).
2. Verifies `X-AIAR-Timestamp` is within 300 seconds of now.
3. Verifies `X-AIAR-Signature` (`v1=<hex>`) using HMAC-SHA-256 over `<timestamp>.<raw_body>` in **constant time**.
4. Checks an idempotency key (`event.id`) before doing real work — retries are normal.
5. Returns 2xx within 5 seconds; otherwise the dispatcher retries with exponential backoff.

The verification is identical across platforms; only the platform glue differs.

## Examples

| Folder | Platform | Notes |
|---|---|---|
| [`cloudflare-workers/`](./cloudflare-workers) | Cloudflare Workers | Web Crypto API, KV for idempotency |
| [`vercel-edge/`](./vercel-edge) | Vercel Edge Functions | Web Crypto API, Vercel KV for idempotency |
| [`aws-lambda/`](./aws-lambda) | AWS Lambda + API Gateway | Node `crypto` module, DynamoDB for idempotency |
| [`express-node/`](./express-node) | Plain Express on Node | Node `crypto`, in-process LRU (replace for prod) |
| [`fastify-typescript/`](./fastify-typescript) | Fastify + TS | Typed body parser, raw-body capture |
| [`deno-deploy/`](./deno-deploy) | Deno Deploy | Deno KV for idempotency |

## Try it without signing up

Each example has a `test.sh` that signs a sample event with a local secret and posts it to the running receiver. You can run the full loop on your laptop in under five minutes:

```bash
cd cloudflare-workers
cp .dev.vars.example .dev.vars   # set AIA_SECRET to anything
npm install && npm run dev       # starts http://localhost:8787
# in another terminal:
bash test.sh                     # posts a signed sample event
```

## Going to production

- Store `AIA_SECRET` in your platform's secret manager. Never commit it.
- Rotate the secret in the AI Act Radar dashboard at least every 90 days.
- Subscribe to the dispatcher's webhook health channel — bounced deliveries surface there before customers notice.
- Idempotency stores need a TTL of at least 7 days; the dispatcher retries up to 24h.

## License

MIT.

---

*AI Act Radar is operated by ligea GmbH, Karlsruhe. Information only — not legal advice.*