Webhooks

Register an address

Settings → Developers → Event notifications. Your address must use https. We show the signing secret once when the address is created.

Events

transcription.finished — A transcription finished
analysis.finished — AI analysis finished
proceeding.ended — A proceeding ended
exhibit.added — An exhibit was added
translation.ready — A translation is ready
credits.low — The credit balance is running low

What we send

request

POST https://your-server.example.com/hooks/aisicario
X-AiSicario-Event: transcription.finished
X-AiSicario-Timestamp: 1775145600
X-AiSicario-Signature: v1=8f3c…

{
  "id": "evt_…",
  "event": "transcription.finished",
  "created_at": "2026-04-02T15:04:11Z",
  "data": { "proceeding_id": "p9a1…", "billed_minutes": 3 }
}

Check the signature

The signature is an HMAC-SHA256 of timestamp + "." + raw body using your secret. Reject anything older than five minutes and always compare in constant time — both libraries do this for you.

javascript

import { verifyWebhook } from "@aisicario/sdk";

const ok = await verifyWebhook(
  process.env.AISICARIO_WEBHOOK_SECRET!,
  rawBody,
  request.headers.get("x-aisicario-timestamp")!,
  request.headers.get("x-aisicario-signature")!,
);
if (!ok) return new Response("bad signature", { status: 401 });

python

from aisicario import verify_webhook

ok = verify_webhook(
    secret=os.environ["AISICARIO_WEBHOOK_SECRET"],
    body=raw_body,
    timestamp=headers["X-AiSicario-Timestamp"],
    signature=headers["X-AiSicario-Signature"],
)

Retries

Reply with any 2xx status within a few seconds. If you don't, we try again after 1, 5, 15, 60 and 180 minutes, then stop. Every attempt is listed in Settings → Developers, and you can send any message again from there. Handle duplicates by treating the event id as unique.