Registration methods
You can set a webhook URL in two ways:Global webhook
Register a URL that receives all job completions for your account:Per-request webhook
Include awebhook_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
2xxstatus 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_idandtypefields let you match the result to your original request. - Respond with
200quickly, then process the result asynchronously.