Skip to main content
Webhooks let you receive moderation results as soon as a job completes, without polling.

Registration methods

You can set a webhook URL in two ways:

Global webhook

Register a URL that receives all job completions for your account:
Calling this endpoint again replaces the previously registered URL.

Per-request webhook

Include a webhook_url field when submitting a moderation request. This overrides the global webhook for that specific job.

Webhook payload

When a job completes, the API sends a POST request to your URL with the following JSON body. The shape depends on the modality.

Prompt moderation result

reason is present only when is_prohibited is true; a prompt that passes omits it.

Image moderation result

categories.custom is only included when at least one custom category ran for the job.

Video moderation result

Delivery behaviour

  • Your server should return a 2xx status code to acknowledge receipt.
  • Delivery failures are logged but not retried. If your server is down, the result is still available via the job status endpoint.
  • The request has a 10-second timeout.

Best practices

  • Use HTTPS for your webhook URL.
  • Validate the payload before processing. The job_id and type fields let you match the result to your original request.
  • Respond with 200 quickly, then process the result asynchronously.