examples/webhook-receiver

Webhook-Receiver für hightrusted CAPTURE

Minimaler Express-Server, der capture.ready / capture.failed Events entgegennimmt, die HMAC-Signatur verifiziert und das fertige PDF im Archiv ablegt.

Use-Case

Wenn du Captures mit mode=webhook anlegst, liefert hightrusted das fertige Ergebnis per HTTP-POST aus — du musst nicht pollen. Dieser Server nimmt das entgegen, prüft, archiviert.

Setup

npm install
export HIGHTRUSTED_API_KEY=ht_live_...
export HIGHTRUSTED_WEBHOOK_SECRET=wh_secret_...
export ARCHIVE_DIR=./archiv

npm start

Der Server lauscht auf Port 8000 (per PORT änderbar). Der Endpoint heißt /webhooks/capture.

Public Reachability

Lokal läuft der Server auf localhost. Damit hightrusted's Server ihn erreichen, brauchst du eine öffentlich erreichbare URL. Drei Optionen:

1. Produktion: hinter nginx auf einem öffentlichen Server, mit TLS
2. Entwicklung: ngrok — ngrok http 8000
3. Eigene Tunnel: Cloudflare Tunnel, Tailscale Funnel, etc.

Capture mit Webhook anlegen

curl -X POST https://capture.hightrusted.net/api/v1/captures \
  -H "Authorization: Bearer ht_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "mode": "webhook",
    "webhook_url": "https://your-domain.tld/webhooks/capture",
    "reference": "case-001"
  }'

Sicherheit

• Signatur immer prüfen — sonst akzeptiert der Server gespoofte Callbacks.
• Schnell mit 200 antworten — der Server muss in <10 s antworten, sonst retried hightrusted. Long-Running-Tasks (PDF herunterladen, in Archiv legen) laufen asynchron, nachdem der 200 raus ist.
• Idempotenz — derselbe Event kann mehrfach kommen (bei Retry). In Produktion solltest du eine Tabelle mit gesehenen event_ids pflegen.

Lizenz

MIT.