Webhooks

Webhooks provide a powerful way to implement custom logic for moderation.

Configure webhook URL

You can configure the webhook URL from the Stream dashboard.

Go to the dashboard
Select the app for which you want to receive webhook events
Click on “Preferences” under the “Moderation” section in the left navigation
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.

`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:

Key	Type	Description
`type`	string	The event type, which is always “moderation_check.completed”
`created_at`	datetime	Timestamp when the moderation check was completed
`entity_id`	string	Unique identifier of the entity that was moderated
`entity_type`	string	Type of the entity that was moderated (e.g., “stream:chat:v1:message”)
`recommended_action`	string	Action recommended by the moderation system (“flag” or “remove”)
`review_queue_item_id`	string	Unique identifier of the associated review queue item

Shapes

ReviewQueueItem Shape

This shape contains the following fields:

Key	Type	Description	Possible Values
`id`	string	Unique identifier of the review queue item
`created_at`	datetime	Timestamp when the review queue item was created
`updated_at`	datetime	Timestamp when the review queue item was last updated
`entity_type`	string	Describes the type of entity under review	Default types include: chat message: `stream:chat:v1:message` feeds activity: `stream:feeds:v2:activity` feeds reaction: `stream:feeds:v2:reaction` user: `stream:user` For custom moderation, the `entity_type` can be any unique string.
`entity_id`	string	The id of the message, activity or reaction
`moderation_payload`	object	exact content which was sent for auto moderation E.g., `{ texts: ["fuck you"], images: ["https://sampleimage.com/test.jpg"], videos: [] }`
`status`	string		Possible values are as following: `partial` when sync moderations results are ready, but async moderations are pending execution `completed` when both sync and async moderations have been run
`recommended_action`		Action recommended by stream moderation engines for the entity/content.	Possible values are as following: `flag` Stream moderation recommended flagging the content for manual review `remove` Stream moderation recommended removing the content.
`completed_at`	datetime	Timestamp when all the moderation engines finished assessing the content
`languages`	array
`severity`	int
`ai_text_severity`	string		Possible values are as following: `NONE` `LOW` `MEDIUM` `HIGH` `CRITICAL`
`reviewed_at`	datetime	Time at which the entity was reviewed
`reviewed_by`	string	Id of the moderator who reviewed the item. This value is set when moderator takes an action on review queue item from dashboard
`message` (only applicable to Chat product)	object	Chat message object under review
`call` (only applicable to Video call moderation)	object	Call object from which moderated frames are taken
`entity_creator`	object	The user who created the entity under review. In case of chat, its the user who sent the message under review. In case of activity feeds, its the actor of the activity/reaction
`entity_creator_id`	string	The id of the user who created the entity under review. In case of chat, its the user who sent the message under review. In case of activity feeds, its the actor of the activity/reaction
`flags`	array	List of reasons the item was flagged for moderation.
`flags_count`	int	Count of flags returned
`bans`	array	List of bans administered to the user
`config_key`	string	Policy key for the moderation policy

ModerationEventFlag Shape

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

Key	Type	Description	Possible Values
`type`	string	Type of the flag. This represents the name of moderation provider which created the flag.	`ai_image` `user_report` When user flags another user `automod_semantic_filters` `automod_platform_circumvention` `block_list` `ai_text` `automod` When user is flagged from Stream’s internal rules. Currently we have 1 rule setup: if more than 3 content from same user is flagged by moderation engines, then automatically flag the user as well. So user ends up in users list page on dashboard `automod_toxicity`
`reason`	string	Description of the reason for the flag
`created_at`	string	Timestamp when the flag was created
`updated_at`	string	Timestamp when the flag was updated
`labels`	array	Classification labels for the content under review from moderation engine (e.g., ai_text, ai_image etc) which created this flag
`result`	object	Complete result object from moderation engine.
`entity_type`	string	Describes the type of entity under review	Default types include: chat message: `stream:chat:v1:message` feeds activity: `stream:feeds:v2:activity` feeds reaction: `stream:feeds:v2:reaction` user: `stream:user` For custom moderation, the `entity_type` can be any unique string.
`entity_id`	string	The id of the message, activity or reaction
`moderation_payload`	object	exact content which was sent for auto moderation E.g., `{ texts: ["fuck you"], images: ["https://sampleimage.com/test.jpg"], videos: [] }`
`review_queue_id`	string	Unique identifier of the review queue item
`user_id`	string	Id of the user that reported the content

ModerationEventActionLog Shape

This shape logs actions taken during the moderation event:

Key	Type	Description	Possible Values
`id`	string	uuid for action log	Unique identifier for the action log
`created_at`	datetime	Timestamp when this action was performed
`type`	string	Type of action performed on the review queue item.	`delete_message` `delete_activity` `delete_reaction` `delete_user` `ban` `custom` `unban` `restore` `unblock`
`user_id`	string	Id of the user (or moderator) who performed the action
`reason`	string	Reason attached by moderator for the action. This can be any string value
`custom`	object	Additional data regarding the action.	In case of `ban` type action, custom object will contain following properties: `timeout` {int} Duration in minutes `shadow` {bool} Shadow block. Only applicable to chat moderation `channel_ban_only` {bool} Weather ban is only for channel. Only applicable to chat moderation `channel_cid` {string} Channel CID in which user is banned. Only applicable to chat moderation In case of `delete_user` action, custom object will contain following properties: `mark_messages_deleted` {bool} `hard_delete` {bool} `delete_conversations` {bool} In case of `delete_reaction` or `delete_message` action, custom object will contain following properties: `hard_delete` {bool}
`target_user_id`	string	This is same as entity creator id of the review queue item.

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:

Key	Type	Description	Possible Values
`entity_id`	string	The id of the entity that was moderated (e.g., message id, activity id, reaction id, or user id).
`entity_type`	string	Describes the type of entity that was moderated.	Default types include: chat message: `stream:chat:v1:message` feeds activity: `stream:feeds:v2:activity` feeds reaction: `stream:feeds:v2:reaction` user: `stream:user` For custom moderation, the `entity_type` can be any unique string.
`recommended_action`	string	Final action recommended by Stream’s moderation engines for the entity/content.	Possible values are as following: `keep` No further action is recommended `flag` Stream moderation recommends flagging the content for manual review `remove` Stream moderation recommends removing the content
`review_queue_item_id`	string	Unique identifier of the associated review queue item created for this moderation check.
`type`	string	Event type	`moderation_check.completed`
`created_at`	datetime	Timestamp when the event was created
`received_at`	datetime	Timestamp when the event was received by your webhook endpoint

Moderation APIs

Multitenant Moderation