Webhooks

Webhooks provide a powerful way to implement custom logic for moderation. Delivery retries, signature verification and the IP allowlist are covered in the webhooks guide.

Configure webhook URL

You can configure the webhook URL from the Stream dashboard.

1. Go to the dashboard
2. Select the app for which you want to receive webhook events
3. Click on "Preferences" under the "Moderation" section in the left navigation
4. Set the URL as shown in the following screenshot

Webhook events

The webhook url will receive following events

• review_queue_item.new
  • This event notifies you of new content available for review. The content could be a message, activity, reaction, or even a user profile.
  • This event is triggered when content is flagged for the first time. Consequently, you'll also receive the associated flags as part of the payload.
• review_queue_item.updated
  • This event notifies you when existing flagged content receives additional flags or when a moderator performs an action on flagged content.
  • The payload includes the new flags or details of the action performed.
• moderation_check.completed
  • This event notifies you when the Moderation Check has been completed.
  • This event is triggered for both flag and non-flag actions.
  • This event is fired when the moderation check for an entity has finished (after sync and async checks). It is emitted even when no flags were raised.
  • The payload includes the entity identifiers and the final recommended_action.
• moderation_rule.triggered
  • This event notifies you when a moderation rule from the Rule Builder is triggered.
  • This event is triggered when rule conditions are met and actions are executed.
  • Available for user, content, and call rule types.
  • For call rules, includes violation_number to track escalation sequences.
  • The payload includes rule information, triggered actions, and entity details.
  • Aggregation rules (keyframes, closed captions, keyframe OCR) include matched_contents when the request supplied content_ids.
  • Use this event to get notified only for the harms or conditions you configured on a rule. See Rule-Triggered Webhooks.
• moderation.text_analysis.complete
  • Fired by Analyze when async_response is true and the text run finishes.
  • Carries the same per-text verdicts as the Analyze HTTP response (action or error per label).
  • Sync and stateless Analyze calls do not emit this event.
• moderation.image_analysis.complete
  • Fired by Analyze when async_response is true and the image run finishes.
  • Carries the same per-image verdicts as the Analyze HTTP response.
  • Sync and stateless Analyze calls do not emit this event.
• moderation.analysis.failed
  • Fired only after Analyze has already returned 201 pending and Stream could not finish the listed work.
  • Carries content_ids only. Provider-level field errors stay on *.complete as error, not on this event.
  • Treat the listed ids as unscreened and resubmit them.

review_queue_item.new

The review_queue_item.new event payload is structured as follows:

{
  "review_queue_item": {
    --> See ReviewQueueItem shape in the table below
  },
  "flags": [
    --> See ModerationEventFlag shape in the table below
  ],
  "action": {
    --> See ModerationEventActionLog shape in the table below
  },
  "type": "review_queue_item.new",
  "created_at": "timestamp",
  "received_at": "timestamp"
}

review_queue_item.updated

The review_queue_item.updated event payload is structured as follows:

{
  "review_queue_item": {
    --> See ReviewQueueItem shape in the table below
  },
  "flags": [
    --> See ModerationEventFlag shape in the table below
  ],
  "action": {
    --> See ModerationEventActionLog shape in the table below
  },
  "type": "review_queue_item.updated",
  "created_at": "timestamp",
  "received_at": "timestamp"
}

moderation_check.completed

The moderation_check.completed event payload is structured as follows:

{
  "type": "moderation_check.completed",
  "created_at": "timestamp",
  "entity_id": "user123-iyVcizkX4KhoiOJf2YOS5",
  "entity_type": "stream:chat:v1:message",
  "recommended_action": "flag",
  "review_queue_item_id": "03eab71c-d2bf-418b-982a-15efcfdebb47"
}

This event contains the following fields:

moderation_rule.triggered

The moderation_rule.triggered event payload is structured as follows:

{
  "type": "moderation_rule.triggered",
  "created_at": "2026-01-20T23:45:04.485362361Z",
  "rule": {
    "id": "0450e7d6-9386-4eb9-a720-f3999979989c",
    "name": "Nudity or hate speech not allowed from men",
    "type": "call",
    "description": "Detects inappropriate content in video calls"
  },
  "violation_number": 1,
  "entity_id": "default:default_test-4013",
  "entity_type": "stream:v1:call",
  "user_id": "test-user-2025b49e-ef45-473f-bb90-4f8f679c8581",
  "triggered_actions": ["mute_video", "call_warning"],
  "review_queue_item_id": "abc123"
}

This event contains the following fields:

Note: Webhook events are sent once per rule per violation number per entity. For call rules with action sequences, if multiple keyframes or closed captions trigger the same rule with the same violation number, only one webhook event is sent.

When an aggregation rule fires, matched_contents lists the items that crossed the threshold. Each entry has type (image or text), id (from content_ids), and published_at. Image rows carry classifications and confidence (or ocr_classifications and severity for OCR rules). Text rows carry classifications and severity.

moderation.text_analysis.complete

Fired once per async Analyze request that included texts. The texts map uses the same shape as the Analyze HTTP response.

{
  "type": "moderation.text_analysis.complete",
  "entity_type": "listing",
  "entity_id": "listing_42",
  "entity_creator_id": "user_42",
  "config_key": "catalog-v1",
  "review_queue_item_id": "rqi_abc",
  "texts": {
    "caption": {
      "id": "cap_42",
      "action": "flag",
      "classifications": [{ "name": "INSULT", "severity": "high" }],
      "severity": "high",
      "language": "en"
    }
  },
  "custom": { "vendor_id": "v_acme" }
}

moderation.image_analysis.complete

Fired once per async Analyze request that included images.

{
  "type": "moderation.image_analysis.complete",
  "entity_type": "listing",
  "entity_id": "listing_42",
  "entity_creator_id": "user_42",
  "config_key": "catalog-v1",
  "review_queue_item_id": "rqi_abc",
  "images": {
    "main_photo": {
      "id": "img_42_main",
      "action": "flag",
      "confidence": 0.924,
      "classifications": [
        {
          "name": "Explicit Nudity",
          "confidence": 0.924,
          "subclassifications": [
            { "name": "Female Nudity", "confidence": 0.91 }
          ]
        }
      ]
    }
  },
  "custom": { "vendor_id": "v_acme" }
}

moderation.analysis.failed

Fired only after Analyze has already acknowledged the request with 201 pending. Stream could not emit a usable *.complete for the listed items. This is not a clean verdict.

{
  "type": "moderation.analysis.failed",
  "entity_type": "listing",
  "entity_id": "listing_42",
  "entity_creator_id": "user_42",
  "config_key": "catalog-v1",
  "content_ids": {
    "caption": "cap_42",
    "main_photo": "img_42_main"
  },
  "custom": { "vendor_id": "v_acme" }
}

Retry only the listed content_ids. A sibling *.complete can still arrive for the other modality.

Shapes

ReviewQueueItem Shape

This shape contains the following fields:

ModerationEventFlag Shape

This shape contains an array of flags associated with the moderation event. Each flag is represented as follows:

ModerationEventActionLog Shape

This shape logs actions taken during the moderation event:

Moderation Check Completed Event Payload Structure

When a moderation check completes, the webhook payload is structured as follows:

{
  "entity_id": "string",
  "entity_type": "string",
  "recommended_action": "keep | flag | remove",
  "review_queue_item_id": "string",
  "type": "moderation_check.completed",
  "created_at": "timestamp",
  "received_at": "timestamp"
}

This shape contains the following fields: