Webhooks

Webhooks are server-to-server callbacks. Instead of polling for results, you give AI Detector API a URL on your side, and we POST results to it when processing is done.

Webhooks are useful for batch jobs that take more than a few seconds, for async pipelines, and for fire-and-forget moderation flows where you don't need to block on the response. They're available on the Pro plan and up.

How AI Detector API webhooks work: when you submit a batch job, you pass an optional webhook_url in the request body. The API returns 202 Accepted immediately with a job ID. As soon as the batch is finished, we POST the results to your URL with a signed header. You verify the signature, idempotently process the payload, and respond with 200 OK.

Verifying the signature. Every webhook delivery includes an X-AIDetectorAPI-Signature header with an HMAC-SHA256 over the raw request body, keyed with your webhook secret. Verify it before acting:

import hmac, hashlib

secret = os.environ["AIDETECTORAPI_WEBHOOK_SECRET"].encode()
expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, signature_header):
    return Response(status=400)

Best practices. Respond 200 fast (under 5 seconds), even if you defer the actual work to a background job. Handle duplicate deliveries idempotently (we may retry on 5xx). Set a per-environment webhook secret so a leaked staging secret cannot replay against production.

Webhook events we send. batch.completed (the most common), batch.failed (when the entire batch errors out), and subscription.updated (when a paying customer changes their plan). The event type lives in the event field of the JSON body.