Overview

Webhooks are HTTP POST requests sent to your configured endpoint when specific events occur in your project. Each webhook contains an event type and associated data, allowing you to respond to moderation results in real-time.

🔒 Security Requirements

HTTPS Required: Your webhook endpoint must use HTTPS for security.

Webhook Secret: Each webhook URL gets a unique secret in the Manual Moderation settings. Compare this secret to validate authenticity.

Webhook Structure

Base Payload Structure

{
  "event": "event.type.name",
  "data": {
    // Event-specific data
  }
}

Base Fields

eventString

The event type that triggered this webhook. Determines the structure of the data field.

dataObject

Event-specific data payload. Structure varies based on event type.

Event Types

moderation.manual.completed

Fired when manual moderation review is completed for a submission. Contains the full moderation results from human review, typically within 48 hours of submission.

Complete Payload Example

{
  "event": "moderation.manual.completed",
  "data": {
    "submission_id": "123e4567-e89b-12d3-a456-426614174000",
    "schema_id": "550e8400-e29b-41d4-a716-446655440000",
    "is_harmful": true,
    "results": {
      "title": {
        "is_harmful": true,
        "detailed": [
          {
            "is_harmful": true,
            "categories": ["violence", "hate"]
          }
        ]
      },
      "description": {
        "is_harmful": false,
        "detailed": [
          {
            "is_harmful": false
          },
          {
            "is_harmful": false
          }
        ]
      },
      "images": {
        "is_harmful": true,
        "detailed": [
          {
            "is_harmful": false
          },
          {
            "is_harmful": true,
            "categories": ["sexual", "violence"]
          }
        ]
      }
    }
  }
}

Data Fields

submission_idUUID

The submission ID that was reviewed.

schema_idUUID

The schema used for moderation.

is_harmfulBoolean

Overall harmful status determined by human reviewers.

resultsObject

Detailed moderation results by component (same structure as automated moderation response).

Webhook Security

Each webhook URL gets a unique secret that you can find in your project'sManual Moderation settings. Simply compare this secret to validate that webhooks come from Outharm.

Webhook Request

POST /your-webhook-endpoint
Content-Type: application/json
X-Outharm-Webhook-Secret: your-webhook-secret-here

{
  "event": "moderation.manual.completed",
  "data": { ... }
}

Security Header

X-Outharm-Webhook-SecretREQUIRED

The webhook secret from your Manual Moderation settings. Compare this value to authenticate the request.

Secret Validation

Validate incoming webhooks by comparing the X-Outharm-Webhook-Secret header with your configured webhook secret.

Best Practices

✅ Always Validate Secrets

Never process webhook events without validating the secret first. This protects against malicious requests.

✅ Idempotent Processing

Handle duplicate webhooks gracefully by using submission_id to detect and ignore duplicate events.

✅ Respond Quickly

Return HTTP 200 within 10 seconds. Process webhooks asynchronously if you need more time.

❌ Don't Use HTTP

Webhook endpoints must use HTTPS. HTTP endpoints will be rejected for security reasons.

❌ Don't Expose Secrets

Store webhook secrets securely in environment variables, never in source code or logs.

Troubleshooting

Common Issues

401 Unauthorized responses:

Check that you're comparing the webhook secret correctly and using the right secret from your settings.

Timeouts:

Ensure your endpoint responds within 10 seconds. Process webhooks asynchronously if needed.

SSL/TLS errors:

Verify your endpoint uses a valid SSL certificate and supports modern TLS versions.

Missing events:

Check your webhook URL configuration in the Manual Moderation settings.

Ready to Get Started?

Configure your webhook endpoint and start receiving real-time moderation notifications securely.

Configure Webhooks

Set up webhook URL and secret

→

Manual Moderation API

Submit content for human review

→

Webhooks API