From 8fe9bc2fecaa0cfc2a24e265c818a60c00fd7f37 Mon Sep 17 00:00:00 2001 From: Thomas Wang Date: Mon, 10 Aug 2026 18:31:22 -0400 Subject: [PATCH 1/6] Revamp trigger event catalog --- docs/capabilities/server/trigger-events.mdx | 504 ++++++++++++++++++ docs/capabilities/server/triggers.mdx | 4 +- sidebars.ts | 1 + .../capabilities/server/trigger-events.mdx | 504 ++++++++++++++++++ .../capabilities/server/triggers.mdx | 4 +- versioned_sidebars/version-0.14-sidebars.json | 1 + 6 files changed, 1014 insertions(+), 4 deletions(-) create mode 100644 docs/capabilities/server/trigger-events.mdx create mode 100644 versioned_docs/version-0.14/capabilities/server/trigger-events.mdx diff --git a/docs/capabilities/server/trigger-events.mdx b/docs/capabilities/server/trigger-events.mdx new file mode 100644 index 00000000..2cf0a260 --- /dev/null +++ b/docs/capabilities/server/trigger-events.mdx @@ -0,0 +1,504 @@ +# Trigger Event Catalog + +Use this catalog to choose a trigger and understand the request sent to your endpoint. For configuration and handler examples, see [Triggers](./triggers). + +The payload types in this page are exported by `@devvit/web/shared`. The tables describe the top-level JSON fields sent to Devvit Web endpoints. Follow the API reference links for the generated event interfaces, and use your installed package's TypeScript definitions as the source of truth for nested objects. + +## Delivery and payload expectations + +- **Delivery is asynchronous.** Reddit state can change between the action and your handler. Fetch the current object when your decision depends on its latest state. +- **An event can be delivered more than once.** Make writes and other side effects idempotent. Do not rely on strict ordering between separate trigger requests. +- **Payload objects are snapshots.** Nested `post`, `comment`, `author`, and `subreddit` objects can be absent when Reddit cannot provide them. Check optional fields before using them. +- **Payloads can be sanitized.** Deleted or removed content can use redacted text and placeholder identities. Moderator and administrator identities can also be masked. +- **Safety processing varies by event.** Submit events favor faster delivery. Create events allow more time for safety processing. An event can be delayed or suppressed, but receiving an event is not a guarantee that its content is safe or will remain available. +- **User-generated content is untrusted.** Escape content before rendering it, and validate it before passing it to another system. + +Every Devvit Web trigger request also contains a `type` discriminator such as `"PostCreate"`. This is useful when multiple trigger keys share one endpoint. + +## Quick reference + +| Trigger key | Represents | Primary payload | Delivery and safety | Details | +| ------------------------------ | --------------------------------------------------- | ----------------------------------------------- | ------------------------------------ | ------------------------------------- | +| `onPostSubmit` | A newly submitted post | Post, author, subreddit | Faster delivery | [View](#onpostsubmit) | +| `onPostCreate` | A newly created post after additional processing | Post, author, subreddit | Safety-processed | [View](#onpostcreate) | +| `onPostUpdate` | An edit to a post's body | Post, author, previous body, subreddit | Safety processing can delay delivery | [View](#onpostupdate) | +| `onPostReport` | A report on a post | Post, reason, subreddit | State-change event | [View](#onpostreport) | +| `onPostDelete` | A post deletion or removal | Post ID, deletion metadata, author, subreddit | State-change event | [View](#onpostdelete) | +| `onPostFlairUpdate` | A post flair change | Post, updater, subreddit | State-change event | [View](#onpostflairupdate) | +| `onPostNsfwUpdate` | A post's NSFW status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostnsfwupdate) | +| `onPostSpoilerUpdate` | A post's spoiler status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostspoilerupdate) | +| `onCommentSubmit` | A newly submitted comment | Comment, author, post, subreddit | Faster delivery | [View](#oncommentsubmit) | +| `onCommentCreate` | A newly created comment after additional processing | Comment, author, post, subreddit | Safety-processed | [View](#oncommentcreate) | +| `onCommentUpdate` | An edit to a comment's body | Comment, author, post, previous body, subreddit | Safety processing can delay delivery | [View](#oncommentupdate) | +| `onCommentReport` | A report on a comment | Comment, reason, subreddit | State-change event | [View](#oncommentreport) | +| `onCommentDelete` | A comment deletion or removal | Comment, post and parent IDs; deletion metadata | State-change event | [View](#oncommentdelete) | +| `onModAction` | An entry in a community's moderation log | Action, moderator, target, subreddit | Moderation event | [View](#onmodaction) | +| `onModMail` | A new modmail message | Message and conversation metadata | Messaging event | [View](#onmodmail) | +| `onAutomoderatorFilterPost` | AutoModerator filtering a post | Post, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfilterpost) | +| `onAutomoderatorFilterComment` | AutoModerator filtering a comment | Comment, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfiltercomment) | +| `onAppInstall` | An app installation in a subreddit | Subreddit, installer | Lifecycle event | [View](#onappinstall) | +| `onAppUpgrade` | An installation moving to a different app version | Subreddit, installer | Lifecycle event | [View](#onappupgrade) | +| `onMentionInCommentCreate` | A new comment that mentions the app username | Comment, author, post, subreddit, mentions | Global, safety-processed event | [View](#onmentionincommentcreate) | + +## Post events + +### onPostSubmit + +**Represents:** A post being submitted to a subreddit. + +**Use it when:** Your app needs to react as quickly as possible, such as assigning initial metadata or starting a latency-sensitive workflow. + +**Delivery and safety:** This event favors faster delivery and can arrive before all safety processing is complete. Known disallowed content can still be suppressed. The post can later be edited, removed, or deleted. + +**Payload:** `OnPostSubmitRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | --------------------------------------- | +| `type` | `"PostSubmit"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the submitted post. | +| `author` | `UserV2` | No | Post author. | +| `subreddit` | `SubredditV2` | No | Subreddit where the post was submitted. | + +**Important behavior:** Do not treat this event as confirmation that the post passed moderation or safety review. If the workflow can wait, prefer [`onPostCreate`](#onpostcreate). + +**API reference:** [PostSubmit](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSubmit) + +### onPostCreate + +**Represents:** A newly created post after Reddit has allowed additional time for safety processing. + +**Use it when:** Your workflow benefits from additional safety processing more than the lowest possible latency. + +**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` and can be delayed or suppressed. Receiving the event does not certify the post as safe, approved, or permanently available. + +**Payload:** `OnPostCreateRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | ------------------------------------- | +| `type` | `"PostCreate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the created post. | +| `author` | `UserV2` | No | Post author. | +| `subreddit` | `SubredditV2` | No | Subreddit where the post was created. | + +**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. + +**API reference:** [PostCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) + +### onPostUpdate + +**Represents:** A change to a post's body. + +**Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited post. + +**Delivery and safety:** Safety processing can delay or suppress this event. The `post` object is a snapshot containing the updated body. + +**Payload:** `OnPostUpdateRequest` + +| Field | Type | Required | Meaning | +| -------------- | -------------- | -------- | ------------------------------------------------------------------------- | +| `type` | `"PostUpdate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the post after the edit. | +| `author` | `UserV2` | No | Post author. This is not necessarily the user who performed every update. | +| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. + +**API reference:** [PostUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostUpdate) + +### onPostReport + +**Represents:** A report being added to a post. + +**Use it when:** Your app assists with report triage, moderation queues, or report-based automation. + +**Delivery and safety:** This is a state-change event. The reported post can already be removed, changed, or unavailable when your handler runs. + +**Payload:** `OnPostReportRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | ---------------------------------------------------------- | +| `type` | `"PostReport"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the reported post. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | + +**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. + +**API reference:** [PostReport](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostReport) + +### onPostDelete + +**Represents:** A post being deleted or removed by a user, moderator, or administrator. + +**Use it when:** Your app needs to clean up derived data, revoke access, or synchronize deletion state. + +**Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted post body. + +**Payload:** `OnPostDeleteRequest` + +| Field | Type | Required | Meaning | +| ----------- | ---------------- | -------- | --------------------------------------------------------------- | +| `type` | `"PostDelete"` | Yes | Event discriminator. | +| `postId` | `string` | Yes | Full post ID, such as `t3_...`. | +| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | +| `author` | `UserV2` | No | Post author when available; deleted identities can be redacted. | +| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | +| `source` | `EventSource` | Yes | Actor category associated with the deletion. It can be unknown. | +| `reason` | `DeletionReason` | Yes | Normalized deletion reason. It can be unspecified or unknown. | +| `subreddit` | `SubredditV2` | No | Subreddit that contained the post. | + +**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. + +**API reference:** [PostDelete](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostDelete), [EventSource](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource), and [DeletionReason](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) + +### onPostFlairUpdate + +**Represents:** A post's flair being added, changed, or cleared. + +**Use it when:** Your app mirrors flair state or starts automation based on the current post flair. + +**Delivery and safety:** This is a state-change event. It is separate from edits to the post body. + +**Payload:** `OnPostFlairUpdateRequest` + +| Field | Type | Required | Meaning | +| ----------- | ------------------- | -------- | ------------------------------------------ | +| `type` | `"PostFlairUpdate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot containing the updated flair. | +| `author` | `UserV2` | No | User who updated the flair when available. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** `author` is the updater, not necessarily the post author. Inspect the flair on `post`; a missing flair can represent a cleared flair. + +**API reference:** [PostFlairUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostFlairUpdate) + +### onPostNsfwUpdate + +**Represents:** A post being marked or unmarked as NSFW. + +**Use it when:** Your app needs to synchronize access, labels, or presentation with the post's current NSFW state. + +**Delivery and safety:** This is a state-change event and can contain NSFW content. The boolean field is the new state. + +**Payload:** `OnPostNsfwUpdateRequest` + +| Field | Type | Required | Meaning | +| ----------- | ------------------ | -------- | ----------------------------------------------- | +| `type` | `"PostNsfwUpdate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the updated post. | +| `author` | `UserV2` | No | User who changed the NSFW state when available. | +| `isNsfw` | `boolean` | Yes | New NSFW state. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** `author` is the updater, not necessarily the post author. Use `isNsfw` instead of inferring the new state from the event name. + +**API reference:** [PostNsfwUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostNsfwUpdate) + +### onPostSpoilerUpdate + +**Represents:** A post being marked or unmarked as a spoiler. + +**Use it when:** Your app needs to synchronize labels or presentation with the post's current spoiler state. + +**Delivery and safety:** This is a state-change event. The boolean field is the new state. + +**Payload:** `OnPostSpoilerUpdateRequest` + +| Field | Type | Required | Meaning | +| ----------- | --------------------- | -------- | -------------------------------------------------- | +| `type` | `"PostSpoilerUpdate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the updated post. | +| `author` | `UserV2` | No | User who changed the spoiler state when available. | +| `isSpoiler` | `boolean` | Yes | New spoiler state. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** `author` is the updater, not necessarily the post author. Use `isSpoiler` instead of assuming the event only represents enabling the flag. + +**API reference:** [PostSpoilerUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSpoilerUpdate) + +## Comment events + +### onCommentSubmit + +**Represents:** A comment being submitted. + +**Use it when:** Your app needs to react as quickly as possible to a new comment. + +**Delivery and safety:** This event favors faster delivery and can arrive before all safety processing is complete. Known disallowed content can still be suppressed. The comment can later be edited, removed, or deleted. + +**Payload:** `OnCommentSubmitRequest` + +| Field | Type | Required | Meaning | +| ----------- | ----------------- | -------- | ------------------------------------------ | +| `type` | `"CommentSubmit"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the submitted comment. | +| `author` | `UserV2` | No | Comment author. | +| `post` | `PostV2` | No | Post containing the comment. | +| `subreddit` | `SubredditV2` | No | Subreddit where the comment was submitted. | + +**Important behavior:** Do not treat this event as confirmation that the comment passed moderation or safety review. If the workflow can wait, prefer [`onCommentCreate`](#oncommentcreate). + +**API reference:** [CommentSubmit](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentSubmit) + +### onCommentCreate + +**Represents:** A newly created comment after Reddit has allowed additional time for safety processing. + +**Use it when:** Your workflow benefits from additional safety processing more than the lowest possible latency. + +**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` and can be delayed or suppressed. Receiving the event does not certify the comment or its parent post as safe, approved, or permanently available. + +**Payload:** `OnCommentCreateRequest` + +| Field | Type | Required | Meaning | +| ----------- | ----------------- | -------- | ---------------------------------------- | +| `type` | `"CommentCreate"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the created comment. | +| `author` | `UserV2` | No | Comment author. | +| `post` | `PostV2` | No | Post containing the comment. | +| `subreddit` | `SubredditV2` | No | Subreddit where the comment was created. | + +**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. + +**API reference:** [CommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) + +### onCommentUpdate + +**Represents:** A change to a comment's body. + +**Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited comment. + +**Delivery and safety:** Safety processing can delay or suppress this event. The `comment` object is a snapshot containing the updated body. + +**Payload:** `OnCommentUpdateRequest` + +| Field | Type | Required | Meaning | +| -------------- | ----------------- | -------- | -------------------------------------------------------- | +| `type` | `"CommentUpdate"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the comment after the edit. | +| `author` | `UserV2` | No | Comment author. | +| `post` | `PostV2` | No | Post containing the comment. | +| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | + +**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. + +**API reference:** [CommentUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentUpdate) + +### onCommentReport + +**Represents:** A report being added to a comment. + +**Use it when:** Your app assists with report triage, moderation queues, or report-based automation. + +**Delivery and safety:** This is a state-change event. The reported comment can already be removed, changed, or unavailable when your handler runs. + +**Payload:** `OnCommentReportRequest` + +| Field | Type | Required | Meaning | +| ----------- | ----------------- | -------- | ---------------------------------------------------------- | +| `type` | `"CommentReport"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the reported comment. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | +| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | + +**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. + +**API reference:** [CommentReport](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentReport) + +### onCommentDelete + +**Represents:** A comment being deleted or removed by a user, moderator, or administrator. + +**Use it when:** Your app needs to clean up derived data, revoke access, or synchronize deletion state. + +**Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted comment body. + +**Payload:** `OnCommentDeleteRequest` + +| Field | Type | Required | Meaning | +| ----------- | ----------------- | -------- | ---------------------------------------------------------------------- | +| `type` | `"CommentDelete"` | Yes | Event discriminator. | +| `commentId` | `string` | Yes | Full comment ID, such as `t1_...`. | +| `postId` | `string` | Yes | Full ID of the post containing the comment. | +| `parentId` | `string` | Yes | Full ID of the parent comment, or the post ID for a top-level comment. | +| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | +| `author` | `UserV2` | No | Comment author when available; deleted identities can be redacted. | +| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | +| `source` | `EventSource` | Yes | Actor category associated with the deletion. It can be unknown. | +| `reason` | `DeletionReason` | Yes | Normalized deletion reason. It can be unspecified or unknown. | +| `subreddit` | `SubredditV2` | No | Subreddit that contained the comment. | + +**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. + +**API reference:** [CommentDelete](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentDelete), [EventSource](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource), and [DeletionReason](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) + +## Moderation and community events + +### onModAction + +**Represents:** A moderator action recorded in a subreddit's moderation log, such as approving, removing, locking, distinguishing, stickying, or changing flair. + +**Use it when:** Your app needs to respond to moderation activity rather than only to the resulting content state. + +**Delivery and safety:** This is a moderation event. Its target content can already be unavailable or sanitized when your handler runs. + +**Payload:** `OnModActionRequest` + +| Field | Type | Required | Meaning | +| --------------- | ------------- | -------- | ----------------------------------------------------- | +| `type` | `"ModAction"` | Yes | Event discriminator. | +| `action` | `string` | No | Moderation action name. | +| `actionedAt` | `string` | No | Action time as an ISO 8601 string. | +| `subreddit` | `SubredditV2` | No | Subreddit where the action occurred. | +| `moderator` | `UserV2` | No | Moderator when available; the identity can be masked. | +| `targetUser` | `UserV2` | No | Target user for user-related actions. | +| `targetComment` | `CommentV2` | No | Target comment for comment-related actions. | +| `targetPost` | `PostV2` | No | Target post for post-related actions. | +| `id` | `string` | No | Identifier for the moderation action. | + +**Important behavior:** Target fields depend on `action`; never assume a particular target is present. Treat action names as an evolving string set and handle unknown values safely. Moderator and administrator identities can be replaced with masked identities. + +**API reference:** [ModActionDefinition](../../api/public-api/type-aliases/ModActionDefinition) + +### onModMail + +**Represents:** A message being sent or received in a modmail conversation associated with the installation. + +**Use it when:** Your app routes, classifies, or synchronizes modmail activity. + +**Delivery and safety:** This is a messaging event. It contains message and conversation metadata, not the message body. + +**Payload:** `OnModMailRequest` + +| Field | Type | Required | Meaning | +| ----------------------- | ------------- | -------- | --------------------------------------------------------------- | +| `type` | `"ModMail"` | Yes | Event discriminator. | +| `messageAuthor` | `UserV2` | No | Message author when available. | +| `createdAt` | `string` | No | Message creation time as an ISO 8601 string. | +| `messageAuthorType` | `string` | Yes | Role used by the author, such as moderator or participant. | +| `conversationState` | `string` | Yes | Current state, such as new, in progress, or archived. | +| `conversationType` | `string` | Yes | Conversation category, such as subreddit-to-user or internal. | +| `isAutoGenerated` | `boolean` | Yes | Whether Reddit or an automated system generated the message. | +| `conversationSubreddit` | `SubredditV2` | No | Subreddit that owns the conversation. | +| `destinationSubreddit` | `SubredditV2` | No | Destination subreddit for subreddit-to-subreddit conversations. | +| `conversationId` | `string` | Yes | Base36 conversation ID without a thing prefix. | +| `messageId` | `string` | Yes | Base36 message ID without a thing prefix. | + +**Important behavior:** Fetch the conversation through the Reddit API when your app needs message contents or current conversation state. `destinationSubreddit` is only relevant to conversation types that have one. + +**API reference:** [ModMailDefinition](../../api/public-api/type-aliases/ModMailDefinition) + +### onAutomoderatorFilterPost + +**Represents:** AutoModerator filtering a post. + +**Use it when:** Your app supplements AutoModerator workflows or records why AutoModerator filtered a post. + +**Delivery and safety:** This event intentionally represents filtered content. Treat the post and reason as sensitive, untrusted input. + +**Payload:** `OnAutomoderatorFilterPostRequest` + +| Field | Type | Required | Meaning | +| ----------- | --------------------------- | -------- | ----------------------------------------------------- | +| `type` | `"AutomoderatorFilterPost"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the filtered post. | +| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | +| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | +| `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onPostDelete` for deletion or removal state. + +**API reference:** [AutomoderatorFilterPost](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterPost) + +### onAutomoderatorFilterComment + +**Represents:** AutoModerator filtering a comment. + +**Use it when:** Your app supplements AutoModerator workflows or records why AutoModerator filtered a comment. + +**Delivery and safety:** This event intentionally represents filtered content. Treat the comment and reason as sensitive, untrusted input. + +**Payload:** `OnAutomoderatorFilterCommentRequest` + +| Field | Type | Required | Meaning | +| ----------- | ------------------------------ | -------- | ----------------------------------------------------- | +| `type` | `"AutomoderatorFilterComment"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the filtered comment. | +| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | +| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | +| `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | + +**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onCommentDelete` for deletion or removal state. + +**API reference:** [AutomoderatorFilterComment](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterComment) + +## App lifecycle events + +### onAppInstall + +**Represents:** The app being installed in a subreddit. + +**Use it when:** Your app needs to initialize installation-scoped data or resources. + +**Delivery and safety:** This lifecycle event is produced by an installation change, not by an ordinary app upload. + +**Payload:** `OnAppInstallRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | --------------------------------------------------- | +| `type` | `"AppInstall"` | Yes | Event discriminator. | +| `subreddit` | `SubredditV2` | No | Subreddit where the app was installed. | +| `installer` | `UserV2` | No | User who initiated the installation when available. | + +**Important behavior:** Make initialization safe to retry because the event can be delivered more than once. Do not require `installer` to be present. + +**API reference:** [AppInstall](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppInstall) + +### onAppUpgrade + +**Represents:** A subreddit installation moving to a different version of the app. + +**Use it when:** Your app needs to migrate installation-scoped data or enable behavior associated with the newly installed version. + +**Delivery and safety:** This lifecycle event is produced when an installation changes version. Uploading or publishing a version does not by itself invoke every installation. + +**Payload:** `OnAppUpgradeRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | ---------------------------------------------- | +| `type` | `"AppUpgrade"` | Yes | Event discriminator. | +| `subreddit` | `SubredditV2` | No | Subreddit whose installation was upgraded. | +| `installer` | `UserV2` | No | User who initiated the upgrade when available. | + +**Important behavior:** Make migrations idempotent and track your own schema or migration version. The payload does not contain the previous and new app version numbers. + +**API reference:** [AppUpgrade](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppUpgrade) + +## Global events + +### onMentionInCommentCreate + +**Represents:** A newly created comment that mentions the app's username. + +**Use it when:** An approved app needs to respond to explicit mentions outside the subreddits where it is ordinarily installed. + +**Delivery and safety:** This limited-access global event allows additional safety processing. Events can be delayed or suppressed for safety reasons. NSFW content can still be present. + +**Payload:** `OnMentionInCommentCreateRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------------------- | -------- | ----------------------------------------------- | +| `type` | `"MentionInCommentCreate"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the comment containing the mention. | +| `author` | `UserV2` | No | Comment author. | +| `post` | `PostV2` | No | Post containing the comment. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | +| `mentions` | `Mentions` | No | Parsed username mentions found in the comment. | + +**Important behavior:** The event has additional access, profile-installation, subreddit, and playtest requirements. Review [App Mention Triggers](./global-triggers) before using it. + +**API reference:** [MentionInCommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/MentionInCommentCreate) diff --git a/docs/capabilities/server/triggers.mdx b/docs/capabilities/server/triggers.mdx index 17255ff4..0f9d5c1e 100644 --- a/docs/capabilities/server/triggers.mdx +++ b/docs/capabilities/server/triggers.mdx @@ -33,7 +33,7 @@ Event triggers let your app automatically respond to a user's or moderator's act - `onAutomoderatorFilterPost` - `onAutomoderatorFilterComment` -A full list of events and their payloads can be found in the [EventTypes documentation](../../api/public-api/@devvit/namespaces/EventTypes/). For more details on Mod specific actions, see [ModActions](../../api/redditapi/models/interfaces/ModAction) and [ModMail](../../api/public-api/type-aliases/ModMailDefinition). +See the [Trigger Event Catalog](./trigger-events) for when each event fires, its delivery and safety behavior, and its top-level payload. For exhaustive generated type definitions, see the [EventTypes API reference](../../api/public-api/@devvit/namespaces/EventTypes/). ## Setting up triggers @@ -155,7 +155,7 @@ router.post( - Avoid creating recursive triggers that could cause infinite loops or crashes (for example, a comment trigger that creates a comment). - Always check the event payload to ensure your app is not the source of the event before taking action. -- Review the [EventTypes documentation](../../api/public-api/@devvit/namespaces/EventTypes/) for details on event payloads. +- Review the [Trigger Event Catalog](./trigger-events) for event behavior and payload details. :::caution Triggers are not guaranteed to deliver only once for a single event. Ensure your app logic is able to handle this case, e.g. checking if content has been recently actioned before taking action again. diff --git a/sidebars.ts b/sidebars.ts index 6d18f15a..9dab2eb4 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -170,6 +170,7 @@ const sidebars: SidebarsConfig = { items: [ "capabilities/server/scheduler", "capabilities/server/triggers", + "capabilities/server/trigger-events", "capabilities/server/global-triggers" ], }, diff --git a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx new file mode 100644 index 00000000..2cf0a260 --- /dev/null +++ b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx @@ -0,0 +1,504 @@ +# Trigger Event Catalog + +Use this catalog to choose a trigger and understand the request sent to your endpoint. For configuration and handler examples, see [Triggers](./triggers). + +The payload types in this page are exported by `@devvit/web/shared`. The tables describe the top-level JSON fields sent to Devvit Web endpoints. Follow the API reference links for the generated event interfaces, and use your installed package's TypeScript definitions as the source of truth for nested objects. + +## Delivery and payload expectations + +- **Delivery is asynchronous.** Reddit state can change between the action and your handler. Fetch the current object when your decision depends on its latest state. +- **An event can be delivered more than once.** Make writes and other side effects idempotent. Do not rely on strict ordering between separate trigger requests. +- **Payload objects are snapshots.** Nested `post`, `comment`, `author`, and `subreddit` objects can be absent when Reddit cannot provide them. Check optional fields before using them. +- **Payloads can be sanitized.** Deleted or removed content can use redacted text and placeholder identities. Moderator and administrator identities can also be masked. +- **Safety processing varies by event.** Submit events favor faster delivery. Create events allow more time for safety processing. An event can be delayed or suppressed, but receiving an event is not a guarantee that its content is safe or will remain available. +- **User-generated content is untrusted.** Escape content before rendering it, and validate it before passing it to another system. + +Every Devvit Web trigger request also contains a `type` discriminator such as `"PostCreate"`. This is useful when multiple trigger keys share one endpoint. + +## Quick reference + +| Trigger key | Represents | Primary payload | Delivery and safety | Details | +| ------------------------------ | --------------------------------------------------- | ----------------------------------------------- | ------------------------------------ | ------------------------------------- | +| `onPostSubmit` | A newly submitted post | Post, author, subreddit | Faster delivery | [View](#onpostsubmit) | +| `onPostCreate` | A newly created post after additional processing | Post, author, subreddit | Safety-processed | [View](#onpostcreate) | +| `onPostUpdate` | An edit to a post's body | Post, author, previous body, subreddit | Safety processing can delay delivery | [View](#onpostupdate) | +| `onPostReport` | A report on a post | Post, reason, subreddit | State-change event | [View](#onpostreport) | +| `onPostDelete` | A post deletion or removal | Post ID, deletion metadata, author, subreddit | State-change event | [View](#onpostdelete) | +| `onPostFlairUpdate` | A post flair change | Post, updater, subreddit | State-change event | [View](#onpostflairupdate) | +| `onPostNsfwUpdate` | A post's NSFW status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostnsfwupdate) | +| `onPostSpoilerUpdate` | A post's spoiler status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostspoilerupdate) | +| `onCommentSubmit` | A newly submitted comment | Comment, author, post, subreddit | Faster delivery | [View](#oncommentsubmit) | +| `onCommentCreate` | A newly created comment after additional processing | Comment, author, post, subreddit | Safety-processed | [View](#oncommentcreate) | +| `onCommentUpdate` | An edit to a comment's body | Comment, author, post, previous body, subreddit | Safety processing can delay delivery | [View](#oncommentupdate) | +| `onCommentReport` | A report on a comment | Comment, reason, subreddit | State-change event | [View](#oncommentreport) | +| `onCommentDelete` | A comment deletion or removal | Comment, post and parent IDs; deletion metadata | State-change event | [View](#oncommentdelete) | +| `onModAction` | An entry in a community's moderation log | Action, moderator, target, subreddit | Moderation event | [View](#onmodaction) | +| `onModMail` | A new modmail message | Message and conversation metadata | Messaging event | [View](#onmodmail) | +| `onAutomoderatorFilterPost` | AutoModerator filtering a post | Post, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfilterpost) | +| `onAutomoderatorFilterComment` | AutoModerator filtering a comment | Comment, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfiltercomment) | +| `onAppInstall` | An app installation in a subreddit | Subreddit, installer | Lifecycle event | [View](#onappinstall) | +| `onAppUpgrade` | An installation moving to a different app version | Subreddit, installer | Lifecycle event | [View](#onappupgrade) | +| `onMentionInCommentCreate` | A new comment that mentions the app username | Comment, author, post, subreddit, mentions | Global, safety-processed event | [View](#onmentionincommentcreate) | + +## Post events + +### onPostSubmit + +**Represents:** A post being submitted to a subreddit. + +**Use it when:** Your app needs to react as quickly as possible, such as assigning initial metadata or starting a latency-sensitive workflow. + +**Delivery and safety:** This event favors faster delivery and can arrive before all safety processing is complete. Known disallowed content can still be suppressed. The post can later be edited, removed, or deleted. + +**Payload:** `OnPostSubmitRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | --------------------------------------- | +| `type` | `"PostSubmit"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the submitted post. | +| `author` | `UserV2` | No | Post author. | +| `subreddit` | `SubredditV2` | No | Subreddit where the post was submitted. | + +**Important behavior:** Do not treat this event as confirmation that the post passed moderation or safety review. If the workflow can wait, prefer [`onPostCreate`](#onpostcreate). + +**API reference:** [PostSubmit](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSubmit) + +### onPostCreate + +**Represents:** A newly created post after Reddit has allowed additional time for safety processing. + +**Use it when:** Your workflow benefits from additional safety processing more than the lowest possible latency. + +**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` and can be delayed or suppressed. Receiving the event does not certify the post as safe, approved, or permanently available. + +**Payload:** `OnPostCreateRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | ------------------------------------- | +| `type` | `"PostCreate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the created post. | +| `author` | `UserV2` | No | Post author. | +| `subreddit` | `SubredditV2` | No | Subreddit where the post was created. | + +**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. + +**API reference:** [PostCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) + +### onPostUpdate + +**Represents:** A change to a post's body. + +**Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited post. + +**Delivery and safety:** Safety processing can delay or suppress this event. The `post` object is a snapshot containing the updated body. + +**Payload:** `OnPostUpdateRequest` + +| Field | Type | Required | Meaning | +| -------------- | -------------- | -------- | ------------------------------------------------------------------------- | +| `type` | `"PostUpdate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the post after the edit. | +| `author` | `UserV2` | No | Post author. This is not necessarily the user who performed every update. | +| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. + +**API reference:** [PostUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostUpdate) + +### onPostReport + +**Represents:** A report being added to a post. + +**Use it when:** Your app assists with report triage, moderation queues, or report-based automation. + +**Delivery and safety:** This is a state-change event. The reported post can already be removed, changed, or unavailable when your handler runs. + +**Payload:** `OnPostReportRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | ---------------------------------------------------------- | +| `type` | `"PostReport"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the reported post. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | + +**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. + +**API reference:** [PostReport](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostReport) + +### onPostDelete + +**Represents:** A post being deleted or removed by a user, moderator, or administrator. + +**Use it when:** Your app needs to clean up derived data, revoke access, or synchronize deletion state. + +**Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted post body. + +**Payload:** `OnPostDeleteRequest` + +| Field | Type | Required | Meaning | +| ----------- | ---------------- | -------- | --------------------------------------------------------------- | +| `type` | `"PostDelete"` | Yes | Event discriminator. | +| `postId` | `string` | Yes | Full post ID, such as `t3_...`. | +| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | +| `author` | `UserV2` | No | Post author when available; deleted identities can be redacted. | +| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | +| `source` | `EventSource` | Yes | Actor category associated with the deletion. It can be unknown. | +| `reason` | `DeletionReason` | Yes | Normalized deletion reason. It can be unspecified or unknown. | +| `subreddit` | `SubredditV2` | No | Subreddit that contained the post. | + +**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. + +**API reference:** [PostDelete](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostDelete), [EventSource](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource), and [DeletionReason](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) + +### onPostFlairUpdate + +**Represents:** A post's flair being added, changed, or cleared. + +**Use it when:** Your app mirrors flair state or starts automation based on the current post flair. + +**Delivery and safety:** This is a state-change event. It is separate from edits to the post body. + +**Payload:** `OnPostFlairUpdateRequest` + +| Field | Type | Required | Meaning | +| ----------- | ------------------- | -------- | ------------------------------------------ | +| `type` | `"PostFlairUpdate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot containing the updated flair. | +| `author` | `UserV2` | No | User who updated the flair when available. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** `author` is the updater, not necessarily the post author. Inspect the flair on `post`; a missing flair can represent a cleared flair. + +**API reference:** [PostFlairUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostFlairUpdate) + +### onPostNsfwUpdate + +**Represents:** A post being marked or unmarked as NSFW. + +**Use it when:** Your app needs to synchronize access, labels, or presentation with the post's current NSFW state. + +**Delivery and safety:** This is a state-change event and can contain NSFW content. The boolean field is the new state. + +**Payload:** `OnPostNsfwUpdateRequest` + +| Field | Type | Required | Meaning | +| ----------- | ------------------ | -------- | ----------------------------------------------- | +| `type` | `"PostNsfwUpdate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the updated post. | +| `author` | `UserV2` | No | User who changed the NSFW state when available. | +| `isNsfw` | `boolean` | Yes | New NSFW state. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** `author` is the updater, not necessarily the post author. Use `isNsfw` instead of inferring the new state from the event name. + +**API reference:** [PostNsfwUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostNsfwUpdate) + +### onPostSpoilerUpdate + +**Represents:** A post being marked or unmarked as a spoiler. + +**Use it when:** Your app needs to synchronize labels or presentation with the post's current spoiler state. + +**Delivery and safety:** This is a state-change event. The boolean field is the new state. + +**Payload:** `OnPostSpoilerUpdateRequest` + +| Field | Type | Required | Meaning | +| ----------- | --------------------- | -------- | -------------------------------------------------- | +| `type` | `"PostSpoilerUpdate"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the updated post. | +| `author` | `UserV2` | No | User who changed the spoiler state when available. | +| `isSpoiler` | `boolean` | Yes | New spoiler state. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** `author` is the updater, not necessarily the post author. Use `isSpoiler` instead of assuming the event only represents enabling the flag. + +**API reference:** [PostSpoilerUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSpoilerUpdate) + +## Comment events + +### onCommentSubmit + +**Represents:** A comment being submitted. + +**Use it when:** Your app needs to react as quickly as possible to a new comment. + +**Delivery and safety:** This event favors faster delivery and can arrive before all safety processing is complete. Known disallowed content can still be suppressed. The comment can later be edited, removed, or deleted. + +**Payload:** `OnCommentSubmitRequest` + +| Field | Type | Required | Meaning | +| ----------- | ----------------- | -------- | ------------------------------------------ | +| `type` | `"CommentSubmit"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the submitted comment. | +| `author` | `UserV2` | No | Comment author. | +| `post` | `PostV2` | No | Post containing the comment. | +| `subreddit` | `SubredditV2` | No | Subreddit where the comment was submitted. | + +**Important behavior:** Do not treat this event as confirmation that the comment passed moderation or safety review. If the workflow can wait, prefer [`onCommentCreate`](#oncommentcreate). + +**API reference:** [CommentSubmit](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentSubmit) + +### onCommentCreate + +**Represents:** A newly created comment after Reddit has allowed additional time for safety processing. + +**Use it when:** Your workflow benefits from additional safety processing more than the lowest possible latency. + +**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` and can be delayed or suppressed. Receiving the event does not certify the comment or its parent post as safe, approved, or permanently available. + +**Payload:** `OnCommentCreateRequest` + +| Field | Type | Required | Meaning | +| ----------- | ----------------- | -------- | ---------------------------------------- | +| `type` | `"CommentCreate"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the created comment. | +| `author` | `UserV2` | No | Comment author. | +| `post` | `PostV2` | No | Post containing the comment. | +| `subreddit` | `SubredditV2` | No | Subreddit where the comment was created. | + +**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. + +**API reference:** [CommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) + +### onCommentUpdate + +**Represents:** A change to a comment's body. + +**Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited comment. + +**Delivery and safety:** Safety processing can delay or suppress this event. The `comment` object is a snapshot containing the updated body. + +**Payload:** `OnCommentUpdateRequest` + +| Field | Type | Required | Meaning | +| -------------- | ----------------- | -------- | -------------------------------------------------------- | +| `type` | `"CommentUpdate"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the comment after the edit. | +| `author` | `UserV2` | No | Comment author. | +| `post` | `PostV2` | No | Post containing the comment. | +| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | + +**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. + +**API reference:** [CommentUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentUpdate) + +### onCommentReport + +**Represents:** A report being added to a comment. + +**Use it when:** Your app assists with report triage, moderation queues, or report-based automation. + +**Delivery and safety:** This is a state-change event. The reported comment can already be removed, changed, or unavailable when your handler runs. + +**Payload:** `OnCommentReportRequest` + +| Field | Type | Required | Meaning | +| ----------- | ----------------- | -------- | ---------------------------------------------------------- | +| `type` | `"CommentReport"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the reported comment. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | +| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | + +**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. + +**API reference:** [CommentReport](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentReport) + +### onCommentDelete + +**Represents:** A comment being deleted or removed by a user, moderator, or administrator. + +**Use it when:** Your app needs to clean up derived data, revoke access, or synchronize deletion state. + +**Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted comment body. + +**Payload:** `OnCommentDeleteRequest` + +| Field | Type | Required | Meaning | +| ----------- | ----------------- | -------- | ---------------------------------------------------------------------- | +| `type` | `"CommentDelete"` | Yes | Event discriminator. | +| `commentId` | `string` | Yes | Full comment ID, such as `t1_...`. | +| `postId` | `string` | Yes | Full ID of the post containing the comment. | +| `parentId` | `string` | Yes | Full ID of the parent comment, or the post ID for a top-level comment. | +| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | +| `author` | `UserV2` | No | Comment author when available; deleted identities can be redacted. | +| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | +| `source` | `EventSource` | Yes | Actor category associated with the deletion. It can be unknown. | +| `reason` | `DeletionReason` | Yes | Normalized deletion reason. It can be unspecified or unknown. | +| `subreddit` | `SubredditV2` | No | Subreddit that contained the comment. | + +**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. + +**API reference:** [CommentDelete](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentDelete), [EventSource](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource), and [DeletionReason](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) + +## Moderation and community events + +### onModAction + +**Represents:** A moderator action recorded in a subreddit's moderation log, such as approving, removing, locking, distinguishing, stickying, or changing flair. + +**Use it when:** Your app needs to respond to moderation activity rather than only to the resulting content state. + +**Delivery and safety:** This is a moderation event. Its target content can already be unavailable or sanitized when your handler runs. + +**Payload:** `OnModActionRequest` + +| Field | Type | Required | Meaning | +| --------------- | ------------- | -------- | ----------------------------------------------------- | +| `type` | `"ModAction"` | Yes | Event discriminator. | +| `action` | `string` | No | Moderation action name. | +| `actionedAt` | `string` | No | Action time as an ISO 8601 string. | +| `subreddit` | `SubredditV2` | No | Subreddit where the action occurred. | +| `moderator` | `UserV2` | No | Moderator when available; the identity can be masked. | +| `targetUser` | `UserV2` | No | Target user for user-related actions. | +| `targetComment` | `CommentV2` | No | Target comment for comment-related actions. | +| `targetPost` | `PostV2` | No | Target post for post-related actions. | +| `id` | `string` | No | Identifier for the moderation action. | + +**Important behavior:** Target fields depend on `action`; never assume a particular target is present. Treat action names as an evolving string set and handle unknown values safely. Moderator and administrator identities can be replaced with masked identities. + +**API reference:** [ModActionDefinition](../../api/public-api/type-aliases/ModActionDefinition) + +### onModMail + +**Represents:** A message being sent or received in a modmail conversation associated with the installation. + +**Use it when:** Your app routes, classifies, or synchronizes modmail activity. + +**Delivery and safety:** This is a messaging event. It contains message and conversation metadata, not the message body. + +**Payload:** `OnModMailRequest` + +| Field | Type | Required | Meaning | +| ----------------------- | ------------- | -------- | --------------------------------------------------------------- | +| `type` | `"ModMail"` | Yes | Event discriminator. | +| `messageAuthor` | `UserV2` | No | Message author when available. | +| `createdAt` | `string` | No | Message creation time as an ISO 8601 string. | +| `messageAuthorType` | `string` | Yes | Role used by the author, such as moderator or participant. | +| `conversationState` | `string` | Yes | Current state, such as new, in progress, or archived. | +| `conversationType` | `string` | Yes | Conversation category, such as subreddit-to-user or internal. | +| `isAutoGenerated` | `boolean` | Yes | Whether Reddit or an automated system generated the message. | +| `conversationSubreddit` | `SubredditV2` | No | Subreddit that owns the conversation. | +| `destinationSubreddit` | `SubredditV2` | No | Destination subreddit for subreddit-to-subreddit conversations. | +| `conversationId` | `string` | Yes | Base36 conversation ID without a thing prefix. | +| `messageId` | `string` | Yes | Base36 message ID without a thing prefix. | + +**Important behavior:** Fetch the conversation through the Reddit API when your app needs message contents or current conversation state. `destinationSubreddit` is only relevant to conversation types that have one. + +**API reference:** [ModMailDefinition](../../api/public-api/type-aliases/ModMailDefinition) + +### onAutomoderatorFilterPost + +**Represents:** AutoModerator filtering a post. + +**Use it when:** Your app supplements AutoModerator workflows or records why AutoModerator filtered a post. + +**Delivery and safety:** This event intentionally represents filtered content. Treat the post and reason as sensitive, untrusted input. + +**Payload:** `OnAutomoderatorFilterPostRequest` + +| Field | Type | Required | Meaning | +| ----------- | --------------------------- | -------- | ----------------------------------------------------- | +| `type` | `"AutomoderatorFilterPost"` | Yes | Event discriminator. | +| `post` | `PostV2` | No | Snapshot of the filtered post. | +| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | +| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | +| `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | + +**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onPostDelete` for deletion or removal state. + +**API reference:** [AutomoderatorFilterPost](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterPost) + +### onAutomoderatorFilterComment + +**Represents:** AutoModerator filtering a comment. + +**Use it when:** Your app supplements AutoModerator workflows or records why AutoModerator filtered a comment. + +**Delivery and safety:** This event intentionally represents filtered content. Treat the comment and reason as sensitive, untrusted input. + +**Payload:** `OnAutomoderatorFilterCommentRequest` + +| Field | Type | Required | Meaning | +| ----------- | ------------------------------ | -------- | ----------------------------------------------------- | +| `type` | `"AutomoderatorFilterComment"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the filtered comment. | +| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | +| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | +| `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | + +**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onCommentDelete` for deletion or removal state. + +**API reference:** [AutomoderatorFilterComment](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterComment) + +## App lifecycle events + +### onAppInstall + +**Represents:** The app being installed in a subreddit. + +**Use it when:** Your app needs to initialize installation-scoped data or resources. + +**Delivery and safety:** This lifecycle event is produced by an installation change, not by an ordinary app upload. + +**Payload:** `OnAppInstallRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | --------------------------------------------------- | +| `type` | `"AppInstall"` | Yes | Event discriminator. | +| `subreddit` | `SubredditV2` | No | Subreddit where the app was installed. | +| `installer` | `UserV2` | No | User who initiated the installation when available. | + +**Important behavior:** Make initialization safe to retry because the event can be delivered more than once. Do not require `installer` to be present. + +**API reference:** [AppInstall](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppInstall) + +### onAppUpgrade + +**Represents:** A subreddit installation moving to a different version of the app. + +**Use it when:** Your app needs to migrate installation-scoped data or enable behavior associated with the newly installed version. + +**Delivery and safety:** This lifecycle event is produced when an installation changes version. Uploading or publishing a version does not by itself invoke every installation. + +**Payload:** `OnAppUpgradeRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------- | -------- | ---------------------------------------------- | +| `type` | `"AppUpgrade"` | Yes | Event discriminator. | +| `subreddit` | `SubredditV2` | No | Subreddit whose installation was upgraded. | +| `installer` | `UserV2` | No | User who initiated the upgrade when available. | + +**Important behavior:** Make migrations idempotent and track your own schema or migration version. The payload does not contain the previous and new app version numbers. + +**API reference:** [AppUpgrade](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppUpgrade) + +## Global events + +### onMentionInCommentCreate + +**Represents:** A newly created comment that mentions the app's username. + +**Use it when:** An approved app needs to respond to explicit mentions outside the subreddits where it is ordinarily installed. + +**Delivery and safety:** This limited-access global event allows additional safety processing. Events can be delayed or suppressed for safety reasons. NSFW content can still be present. + +**Payload:** `OnMentionInCommentCreateRequest` + +| Field | Type | Required | Meaning | +| ----------- | -------------------------- | -------- | ----------------------------------------------- | +| `type` | `"MentionInCommentCreate"` | Yes | Event discriminator. | +| `comment` | `CommentV2` | No | Snapshot of the comment containing the mention. | +| `author` | `UserV2` | No | Comment author. | +| `post` | `PostV2` | No | Post containing the comment. | +| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | +| `mentions` | `Mentions` | No | Parsed username mentions found in the comment. | + +**Important behavior:** The event has additional access, profile-installation, subreddit, and playtest requirements. Review [App Mention Triggers](./global-triggers) before using it. + +**API reference:** [MentionInCommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/MentionInCommentCreate) diff --git a/versioned_docs/version-0.14/capabilities/server/triggers.mdx b/versioned_docs/version-0.14/capabilities/server/triggers.mdx index 17255ff4..0f9d5c1e 100644 --- a/versioned_docs/version-0.14/capabilities/server/triggers.mdx +++ b/versioned_docs/version-0.14/capabilities/server/triggers.mdx @@ -33,7 +33,7 @@ Event triggers let your app automatically respond to a user's or moderator's act - `onAutomoderatorFilterPost` - `onAutomoderatorFilterComment` -A full list of events and their payloads can be found in the [EventTypes documentation](../../api/public-api/@devvit/namespaces/EventTypes/). For more details on Mod specific actions, see [ModActions](../../api/redditapi/models/interfaces/ModAction) and [ModMail](../../api/public-api/type-aliases/ModMailDefinition). +See the [Trigger Event Catalog](./trigger-events) for when each event fires, its delivery and safety behavior, and its top-level payload. For exhaustive generated type definitions, see the [EventTypes API reference](../../api/public-api/@devvit/namespaces/EventTypes/). ## Setting up triggers @@ -155,7 +155,7 @@ router.post( - Avoid creating recursive triggers that could cause infinite loops or crashes (for example, a comment trigger that creates a comment). - Always check the event payload to ensure your app is not the source of the event before taking action. -- Review the [EventTypes documentation](../../api/public-api/@devvit/namespaces/EventTypes/) for details on event payloads. +- Review the [Trigger Event Catalog](./trigger-events) for event behavior and payload details. :::caution Triggers are not guaranteed to deliver only once for a single event. Ensure your app logic is able to handle this case, e.g. checking if content has been recently actioned before taking action again. diff --git a/versioned_sidebars/version-0.14-sidebars.json b/versioned_sidebars/version-0.14-sidebars.json index 2991d31f..c57d46c2 100644 --- a/versioned_sidebars/version-0.14-sidebars.json +++ b/versioned_sidebars/version-0.14-sidebars.json @@ -155,6 +155,7 @@ "items": [ "capabilities/server/scheduler", "capabilities/server/triggers", + "capabilities/server/trigger-events", "capabilities/server/global-triggers" ] }, From 1a7a055ea1c6d773df6e8c41c6f3dd1f163ae764 Mon Sep 17 00:00:00 2001 From: Thomas Wang Date: Tue, 11 Aug 2026 17:19:26 -0400 Subject: [PATCH 2/6] Clarify trigger safety processing --- docs/capabilities/server/trigger-events.mdx | 48 +++++++++++-------- docs/capabilities/server/triggers.mdx | 38 +++++++-------- .../capabilities/server/trigger-events.mdx | 48 +++++++++++-------- .../capabilities/server/triggers.mdx | 38 +++++++-------- 4 files changed, 96 insertions(+), 76 deletions(-) diff --git a/docs/capabilities/server/trigger-events.mdx b/docs/capabilities/server/trigger-events.mdx index 2cf0a260..54fb1940 100644 --- a/docs/capabilities/server/trigger-events.mdx +++ b/docs/capabilities/server/trigger-events.mdx @@ -10,26 +10,36 @@ The payload types in this page are exported by `@devvit/web/shared`. The tables - **An event can be delivered more than once.** Make writes and other side effects idempotent. Do not rely on strict ordering between separate trigger requests. - **Payload objects are snapshots.** Nested `post`, `comment`, `author`, and `subreddit` objects can be absent when Reddit cannot provide them. Check optional fields before using them. - **Payloads can be sanitized.** Deleted or removed content can use redacted text and placeholder identities. Moderator and administrator identities can also be masked. -- **Safety processing varies by event.** Submit events favor faster delivery. Create events allow more time for safety processing. An event can be delayed or suppressed, but receiving an event is not a guarantee that its content is safe or will remain available. +- **Safety processing is a narrow delivery gate.** For eligible content with uploaded images or video, Reddit can allow time for signals that detect certain high-severity illegal sexual content. See [What safety processing means](#what-safety-processing-means). - **User-generated content is untrusted.** Escape content before rendering it, and validate it before passing it to another system. Every Devvit Web trigger request also contains a `type` discriminator such as `"PostCreate"`. This is useful when multiple trigger keys share one endpoint. +### What safety processing means + +Safety processing for Devvit trigger delivery is not a general moderation review. For eligible posts and comments that contain uploaded images or video, Reddit may allow time for signals that detect certain high-severity illegal sexual content, including child sexual abuse material (CSAM) and non-consensual intimate media (NCIM). If a matching signal is known, the trigger event can be suppressed. + +These checks do not certify that content is free of ordinary NSFW material, spam, harassment, or every other policy or community-rule violation. Reddit, AutoModerator, and community moderators can independently remove or change content before or after your handler runs. + +Not every event has an applicable media check; most text-only posts and comments do not. Submit events do not wait for an outstanding check, while create events allow time for applicable checks to complete. A create event can still be delivered when no check applies or when a result is unavailable, so delivery is never proof that content is safe or approved. + +Safety checking determines whether an event is delivered. Payload sanitization and identity redaction are separate protections that determine what data the event contains. + ## Quick reference | Trigger key | Represents | Primary payload | Delivery and safety | Details | | ------------------------------ | --------------------------------------------------- | ----------------------------------------------- | ------------------------------------ | ------------------------------------- | -| `onPostSubmit` | A newly submitted post | Post, author, subreddit | Faster delivery | [View](#onpostsubmit) | -| `onPostCreate` | A newly created post after additional processing | Post, author, subreddit | Safety-processed | [View](#onpostcreate) | -| `onPostUpdate` | An edit to a post's body | Post, author, previous body, subreddit | Safety processing can delay delivery | [View](#onpostupdate) | +| `onPostSubmit` | A newly submitted post | Post, author, subreddit | Does not wait for media checks | [View](#onpostsubmit) | +| `onPostCreate` | A newly created post after additional processing | Post, author, subreddit | Allows time for media checks | [View](#onpostcreate) | +| `onPostUpdate` | An edit to a post's body | Post, author, previous body, subreddit | Allows applicable media checks | [View](#onpostupdate) | | `onPostReport` | A report on a post | Post, reason, subreddit | State-change event | [View](#onpostreport) | | `onPostDelete` | A post deletion or removal | Post ID, deletion metadata, author, subreddit | State-change event | [View](#onpostdelete) | | `onPostFlairUpdate` | A post flair change | Post, updater, subreddit | State-change event | [View](#onpostflairupdate) | | `onPostNsfwUpdate` | A post's NSFW status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostnsfwupdate) | | `onPostSpoilerUpdate` | A post's spoiler status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostspoilerupdate) | -| `onCommentSubmit` | A newly submitted comment | Comment, author, post, subreddit | Faster delivery | [View](#oncommentsubmit) | -| `onCommentCreate` | A newly created comment after additional processing | Comment, author, post, subreddit | Safety-processed | [View](#oncommentcreate) | -| `onCommentUpdate` | An edit to a comment's body | Comment, author, post, previous body, subreddit | Safety processing can delay delivery | [View](#oncommentupdate) | +| `onCommentSubmit` | A newly submitted comment | Comment, author, post, subreddit | Does not wait for media checks | [View](#oncommentsubmit) | +| `onCommentCreate` | A newly created comment after additional processing | Comment, author, post, subreddit | Allows time for media checks | [View](#oncommentcreate) | +| `onCommentUpdate` | An edit to a comment's body | Comment, author, post, previous body, subreddit | Allows applicable media checks | [View](#oncommentupdate) | | `onCommentReport` | A report on a comment | Comment, reason, subreddit | State-change event | [View](#oncommentreport) | | `onCommentDelete` | A comment deletion or removal | Comment, post and parent IDs; deletion metadata | State-change event | [View](#oncommentdelete) | | `onModAction` | An entry in a community's moderation log | Action, moderator, target, subreddit | Moderation event | [View](#onmodaction) | @@ -38,7 +48,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" | `onAutomoderatorFilterComment` | AutoModerator filtering a comment | Comment, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfiltercomment) | | `onAppInstall` | An app installation in a subreddit | Subreddit, installer | Lifecycle event | [View](#onappinstall) | | `onAppUpgrade` | An installation moving to a different app version | Subreddit, installer | Lifecycle event | [View](#onappupgrade) | -| `onMentionInCommentCreate` | A new comment that mentions the app username | Comment, author, post, subreddit, mentions | Global, safety-processed event | [View](#onmentionincommentcreate) | +| `onMentionInCommentCreate` | A new comment that mentions the app username | Comment, author, post, subreddit, mentions | Global; allows time for media checks | [View](#onmentionincommentcreate) | ## Post events @@ -48,7 +58,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** Your app needs to react as quickly as possible, such as assigning initial metadata or starting a latency-sensitive workflow. -**Delivery and safety:** This event favors faster delivery and can arrive before all safety processing is complete. Known disallowed content can still be suppressed. The post can later be edited, removed, or deleted. +**Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The post can later be edited, removed, or deleted. **Payload:** `OnPostSubmitRequest` @@ -65,11 +75,11 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" ### onPostCreate -**Represents:** A newly created post after Reddit has allowed additional time for safety processing. +**Represents:** A newly created post after Reddit has allowed time for applicable media safety checks. -**Use it when:** Your workflow benefits from additional safety processing more than the lowest possible latency. +**Use it when:** Your workflow benefits from allowing applicable media safety checks more time than the lowest-latency notification permits. -**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` and can be delayed or suppressed. Receiving the event does not certify the post as safe, approved, or permanently available. +**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. **Payload:** `OnPostCreateRequest` @@ -90,7 +100,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited post. -**Delivery and safety:** Safety processing can delay or suppress this event. The `post` object is a snapshot containing the updated body. +**Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `post` object is a snapshot containing the updated body. **Payload:** `OnPostUpdateRequest` @@ -225,7 +235,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** Your app needs to react as quickly as possible to a new comment. -**Delivery and safety:** This event favors faster delivery and can arrive before all safety processing is complete. Known disallowed content can still be suppressed. The comment can later be edited, removed, or deleted. +**Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The comment can later be edited, removed, or deleted. **Payload:** `OnCommentSubmitRequest` @@ -243,11 +253,11 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" ### onCommentCreate -**Represents:** A newly created comment after Reddit has allowed additional time for safety processing. +**Represents:** A newly created comment after Reddit has allowed time for applicable media safety checks. -**Use it when:** Your workflow benefits from additional safety processing more than the lowest possible latency. +**Use it when:** Your workflow benefits from allowing applicable media safety checks more time than the lowest-latency notification permits. -**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` and can be delayed or suppressed. Receiving the event does not certify the comment or its parent post as safe, approved, or permanently available. +**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. **Payload:** `OnCommentCreateRequest` @@ -269,7 +279,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited comment. -**Delivery and safety:** Safety processing can delay or suppress this event. The `comment` object is a snapshot containing the updated body. +**Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `comment` object is a snapshot containing the updated body. **Payload:** `OnCommentUpdateRequest` @@ -486,7 +496,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** An approved app needs to respond to explicit mentions outside the subreddits where it is ordinarily installed. -**Delivery and safety:** This limited-access global event allows additional safety processing. Events can be delayed or suppressed for safety reasons. NSFW content can still be present. +**Delivery and safety:** This limited-access global event allows time for applicable [media safety checks](#what-safety-processing-means) on the comment and its parent post. A known match can suppress the event, but ordinary NSFW content can still be present. **Payload:** `OnMentionInCommentCreateRequest` diff --git a/docs/capabilities/server/triggers.mdx b/docs/capabilities/server/triggers.mdx index 0f9d5c1e..eaa72d7f 100644 --- a/docs/capabilities/server/triggers.mdx +++ b/docs/capabilities/server/triggers.mdx @@ -13,25 +13,25 @@ A trigger is an action you can build into your app that will occur automatically Event triggers let your app automatically respond to a user's or moderator's action. The following trigger types are supported: -- `onPostSubmit` -- `onPostCreate` -- `onPostUpdate` -- `onPostReport` -- `onPostDelete` -- `onPostFlairUpdate` -- `onCommentCreate` -- `onCommentDelete` -- `onCommentReport` -- `onCommentSubmit` -- `onCommentUpdate` -- `onPostNsfwUpdate` -- `onPostSpoilerUpdate` -- `onAppInstall` -- `onAppUpgrade` -- `onModAction` -- `onModMail` -- `onAutomoderatorFilterPost` -- `onAutomoderatorFilterComment` +- [`onPostSubmit`](./trigger-events#onpostsubmit) +- [`onPostCreate`](./trigger-events#onpostcreate) +- [`onPostUpdate`](./trigger-events#onpostupdate) +- [`onPostReport`](./trigger-events#onpostreport) +- [`onPostDelete`](./trigger-events#onpostdelete) +- [`onPostFlairUpdate`](./trigger-events#onpostflairupdate) +- [`onCommentCreate`](./trigger-events#oncommentcreate) +- [`onCommentDelete`](./trigger-events#oncommentdelete) +- [`onCommentReport`](./trigger-events#oncommentreport) +- [`onCommentSubmit`](./trigger-events#oncommentsubmit) +- [`onCommentUpdate`](./trigger-events#oncommentupdate) +- [`onPostNsfwUpdate`](./trigger-events#onpostnsfwupdate) +- [`onPostSpoilerUpdate`](./trigger-events#onpostspoilerupdate) +- [`onAppInstall`](./trigger-events#onappinstall) +- [`onAppUpgrade`](./trigger-events#onappupgrade) +- [`onModAction`](./trigger-events#onmodaction) +- [`onModMail`](./trigger-events#onmodmail) +- [`onAutomoderatorFilterPost`](./trigger-events#onautomoderatorfilterpost) +- [`onAutomoderatorFilterComment`](./trigger-events#onautomoderatorfiltercomment) See the [Trigger Event Catalog](./trigger-events) for when each event fires, its delivery and safety behavior, and its top-level payload. For exhaustive generated type definitions, see the [EventTypes API reference](../../api/public-api/@devvit/namespaces/EventTypes/). diff --git a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx index 2cf0a260..54fb1940 100644 --- a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx +++ b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx @@ -10,26 +10,36 @@ The payload types in this page are exported by `@devvit/web/shared`. The tables - **An event can be delivered more than once.** Make writes and other side effects idempotent. Do not rely on strict ordering between separate trigger requests. - **Payload objects are snapshots.** Nested `post`, `comment`, `author`, and `subreddit` objects can be absent when Reddit cannot provide them. Check optional fields before using them. - **Payloads can be sanitized.** Deleted or removed content can use redacted text and placeholder identities. Moderator and administrator identities can also be masked. -- **Safety processing varies by event.** Submit events favor faster delivery. Create events allow more time for safety processing. An event can be delayed or suppressed, but receiving an event is not a guarantee that its content is safe or will remain available. +- **Safety processing is a narrow delivery gate.** For eligible content with uploaded images or video, Reddit can allow time for signals that detect certain high-severity illegal sexual content. See [What safety processing means](#what-safety-processing-means). - **User-generated content is untrusted.** Escape content before rendering it, and validate it before passing it to another system. Every Devvit Web trigger request also contains a `type` discriminator such as `"PostCreate"`. This is useful when multiple trigger keys share one endpoint. +### What safety processing means + +Safety processing for Devvit trigger delivery is not a general moderation review. For eligible posts and comments that contain uploaded images or video, Reddit may allow time for signals that detect certain high-severity illegal sexual content, including child sexual abuse material (CSAM) and non-consensual intimate media (NCIM). If a matching signal is known, the trigger event can be suppressed. + +These checks do not certify that content is free of ordinary NSFW material, spam, harassment, or every other policy or community-rule violation. Reddit, AutoModerator, and community moderators can independently remove or change content before or after your handler runs. + +Not every event has an applicable media check; most text-only posts and comments do not. Submit events do not wait for an outstanding check, while create events allow time for applicable checks to complete. A create event can still be delivered when no check applies or when a result is unavailable, so delivery is never proof that content is safe or approved. + +Safety checking determines whether an event is delivered. Payload sanitization and identity redaction are separate protections that determine what data the event contains. + ## Quick reference | Trigger key | Represents | Primary payload | Delivery and safety | Details | | ------------------------------ | --------------------------------------------------- | ----------------------------------------------- | ------------------------------------ | ------------------------------------- | -| `onPostSubmit` | A newly submitted post | Post, author, subreddit | Faster delivery | [View](#onpostsubmit) | -| `onPostCreate` | A newly created post after additional processing | Post, author, subreddit | Safety-processed | [View](#onpostcreate) | -| `onPostUpdate` | An edit to a post's body | Post, author, previous body, subreddit | Safety processing can delay delivery | [View](#onpostupdate) | +| `onPostSubmit` | A newly submitted post | Post, author, subreddit | Does not wait for media checks | [View](#onpostsubmit) | +| `onPostCreate` | A newly created post after additional processing | Post, author, subreddit | Allows time for media checks | [View](#onpostcreate) | +| `onPostUpdate` | An edit to a post's body | Post, author, previous body, subreddit | Allows applicable media checks | [View](#onpostupdate) | | `onPostReport` | A report on a post | Post, reason, subreddit | State-change event | [View](#onpostreport) | | `onPostDelete` | A post deletion or removal | Post ID, deletion metadata, author, subreddit | State-change event | [View](#onpostdelete) | | `onPostFlairUpdate` | A post flair change | Post, updater, subreddit | State-change event | [View](#onpostflairupdate) | | `onPostNsfwUpdate` | A post's NSFW status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostnsfwupdate) | | `onPostSpoilerUpdate` | A post's spoiler status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostspoilerupdate) | -| `onCommentSubmit` | A newly submitted comment | Comment, author, post, subreddit | Faster delivery | [View](#oncommentsubmit) | -| `onCommentCreate` | A newly created comment after additional processing | Comment, author, post, subreddit | Safety-processed | [View](#oncommentcreate) | -| `onCommentUpdate` | An edit to a comment's body | Comment, author, post, previous body, subreddit | Safety processing can delay delivery | [View](#oncommentupdate) | +| `onCommentSubmit` | A newly submitted comment | Comment, author, post, subreddit | Does not wait for media checks | [View](#oncommentsubmit) | +| `onCommentCreate` | A newly created comment after additional processing | Comment, author, post, subreddit | Allows time for media checks | [View](#oncommentcreate) | +| `onCommentUpdate` | An edit to a comment's body | Comment, author, post, previous body, subreddit | Allows applicable media checks | [View](#oncommentupdate) | | `onCommentReport` | A report on a comment | Comment, reason, subreddit | State-change event | [View](#oncommentreport) | | `onCommentDelete` | A comment deletion or removal | Comment, post and parent IDs; deletion metadata | State-change event | [View](#oncommentdelete) | | `onModAction` | An entry in a community's moderation log | Action, moderator, target, subreddit | Moderation event | [View](#onmodaction) | @@ -38,7 +48,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" | `onAutomoderatorFilterComment` | AutoModerator filtering a comment | Comment, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfiltercomment) | | `onAppInstall` | An app installation in a subreddit | Subreddit, installer | Lifecycle event | [View](#onappinstall) | | `onAppUpgrade` | An installation moving to a different app version | Subreddit, installer | Lifecycle event | [View](#onappupgrade) | -| `onMentionInCommentCreate` | A new comment that mentions the app username | Comment, author, post, subreddit, mentions | Global, safety-processed event | [View](#onmentionincommentcreate) | +| `onMentionInCommentCreate` | A new comment that mentions the app username | Comment, author, post, subreddit, mentions | Global; allows time for media checks | [View](#onmentionincommentcreate) | ## Post events @@ -48,7 +58,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** Your app needs to react as quickly as possible, such as assigning initial metadata or starting a latency-sensitive workflow. -**Delivery and safety:** This event favors faster delivery and can arrive before all safety processing is complete. Known disallowed content can still be suppressed. The post can later be edited, removed, or deleted. +**Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The post can later be edited, removed, or deleted. **Payload:** `OnPostSubmitRequest` @@ -65,11 +75,11 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" ### onPostCreate -**Represents:** A newly created post after Reddit has allowed additional time for safety processing. +**Represents:** A newly created post after Reddit has allowed time for applicable media safety checks. -**Use it when:** Your workflow benefits from additional safety processing more than the lowest possible latency. +**Use it when:** Your workflow benefits from allowing applicable media safety checks more time than the lowest-latency notification permits. -**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` and can be delayed or suppressed. Receiving the event does not certify the post as safe, approved, or permanently available. +**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. **Payload:** `OnPostCreateRequest` @@ -90,7 +100,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited post. -**Delivery and safety:** Safety processing can delay or suppress this event. The `post` object is a snapshot containing the updated body. +**Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `post` object is a snapshot containing the updated body. **Payload:** `OnPostUpdateRequest` @@ -225,7 +235,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** Your app needs to react as quickly as possible to a new comment. -**Delivery and safety:** This event favors faster delivery and can arrive before all safety processing is complete. Known disallowed content can still be suppressed. The comment can later be edited, removed, or deleted. +**Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The comment can later be edited, removed, or deleted. **Payload:** `OnCommentSubmitRequest` @@ -243,11 +253,11 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" ### onCommentCreate -**Represents:** A newly created comment after Reddit has allowed additional time for safety processing. +**Represents:** A newly created comment after Reddit has allowed time for applicable media safety checks. -**Use it when:** Your workflow benefits from additional safety processing more than the lowest possible latency. +**Use it when:** Your workflow benefits from allowing applicable media safety checks more time than the lowest-latency notification permits. -**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` and can be delayed or suppressed. Receiving the event does not certify the comment or its parent post as safe, approved, or permanently available. +**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. **Payload:** `OnCommentCreateRequest` @@ -269,7 +279,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited comment. -**Delivery and safety:** Safety processing can delay or suppress this event. The `comment` object is a snapshot containing the updated body. +**Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `comment` object is a snapshot containing the updated body. **Payload:** `OnCommentUpdateRequest` @@ -486,7 +496,7 @@ Every Devvit Web trigger request also contains a `type` discriminator such as `" **Use it when:** An approved app needs to respond to explicit mentions outside the subreddits where it is ordinarily installed. -**Delivery and safety:** This limited-access global event allows additional safety processing. Events can be delayed or suppressed for safety reasons. NSFW content can still be present. +**Delivery and safety:** This limited-access global event allows time for applicable [media safety checks](#what-safety-processing-means) on the comment and its parent post. A known match can suppress the event, but ordinary NSFW content can still be present. **Payload:** `OnMentionInCommentCreateRequest` diff --git a/versioned_docs/version-0.14/capabilities/server/triggers.mdx b/versioned_docs/version-0.14/capabilities/server/triggers.mdx index 0f9d5c1e..eaa72d7f 100644 --- a/versioned_docs/version-0.14/capabilities/server/triggers.mdx +++ b/versioned_docs/version-0.14/capabilities/server/triggers.mdx @@ -13,25 +13,25 @@ A trigger is an action you can build into your app that will occur automatically Event triggers let your app automatically respond to a user's or moderator's action. The following trigger types are supported: -- `onPostSubmit` -- `onPostCreate` -- `onPostUpdate` -- `onPostReport` -- `onPostDelete` -- `onPostFlairUpdate` -- `onCommentCreate` -- `onCommentDelete` -- `onCommentReport` -- `onCommentSubmit` -- `onCommentUpdate` -- `onPostNsfwUpdate` -- `onPostSpoilerUpdate` -- `onAppInstall` -- `onAppUpgrade` -- `onModAction` -- `onModMail` -- `onAutomoderatorFilterPost` -- `onAutomoderatorFilterComment` +- [`onPostSubmit`](./trigger-events#onpostsubmit) +- [`onPostCreate`](./trigger-events#onpostcreate) +- [`onPostUpdate`](./trigger-events#onpostupdate) +- [`onPostReport`](./trigger-events#onpostreport) +- [`onPostDelete`](./trigger-events#onpostdelete) +- [`onPostFlairUpdate`](./trigger-events#onpostflairupdate) +- [`onCommentCreate`](./trigger-events#oncommentcreate) +- [`onCommentDelete`](./trigger-events#oncommentdelete) +- [`onCommentReport`](./trigger-events#oncommentreport) +- [`onCommentSubmit`](./trigger-events#oncommentsubmit) +- [`onCommentUpdate`](./trigger-events#oncommentupdate) +- [`onPostNsfwUpdate`](./trigger-events#onpostnsfwupdate) +- [`onPostSpoilerUpdate`](./trigger-events#onpostspoilerupdate) +- [`onAppInstall`](./trigger-events#onappinstall) +- [`onAppUpgrade`](./trigger-events#onappupgrade) +- [`onModAction`](./trigger-events#onmodaction) +- [`onModMail`](./trigger-events#onmodmail) +- [`onAutomoderatorFilterPost`](./trigger-events#onautomoderatorfilterpost) +- [`onAutomoderatorFilterComment`](./trigger-events#onautomoderatorfiltercomment) See the [Trigger Event Catalog](./trigger-events) for when each event fires, its delivery and safety behavior, and its top-level payload. For exhaustive generated type definitions, see the [EventTypes API reference](../../api/public-api/@devvit/namespaces/EventTypes/). From 50de717f4b181628d3b96d44c2b888f9fa10b4ca Mon Sep 17 00:00:00 2001 From: Thomas Wang Date: Tue, 11 Aug 2026 17:20:27 -0400 Subject: [PATCH 3/6] Remove trigger usage guidance --- docs/capabilities/server/trigger-events.mdx | 40 ------------------- .../capabilities/server/trigger-events.mdx | 40 ------------------- 2 files changed, 80 deletions(-) diff --git a/docs/capabilities/server/trigger-events.mdx b/docs/capabilities/server/trigger-events.mdx index 54fb1940..04eea59a 100644 --- a/docs/capabilities/server/trigger-events.mdx +++ b/docs/capabilities/server/trigger-events.mdx @@ -56,8 +56,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post being submitted to a subreddit. -**Use it when:** Your app needs to react as quickly as possible, such as assigning initial metadata or starting a latency-sensitive workflow. - **Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The post can later be edited, removed, or deleted. **Payload:** `OnPostSubmitRequest` @@ -77,8 +75,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created post after Reddit has allowed time for applicable media safety checks. -**Use it when:** Your workflow benefits from allowing applicable media safety checks more time than the lowest-latency notification permits. - **Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. **Payload:** `OnPostCreateRequest` @@ -98,8 +94,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A change to a post's body. -**Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited post. - **Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `post` object is a snapshot containing the updated body. **Payload:** `OnPostUpdateRequest` @@ -120,8 +114,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A report being added to a post. -**Use it when:** Your app assists with report triage, moderation queues, or report-based automation. - **Delivery and safety:** This is a state-change event. The reported post can already be removed, changed, or unavailable when your handler runs. **Payload:** `OnPostReportRequest` @@ -141,8 +133,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post being deleted or removed by a user, moderator, or administrator. -**Use it when:** Your app needs to clean up derived data, revoke access, or synchronize deletion state. - **Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted post body. **Payload:** `OnPostDeleteRequest` @@ -166,8 +156,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post's flair being added, changed, or cleared. -**Use it when:** Your app mirrors flair state or starts automation based on the current post flair. - **Delivery and safety:** This is a state-change event. It is separate from edits to the post body. **Payload:** `OnPostFlairUpdateRequest` @@ -187,8 +175,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post being marked or unmarked as NSFW. -**Use it when:** Your app needs to synchronize access, labels, or presentation with the post's current NSFW state. - **Delivery and safety:** This is a state-change event and can contain NSFW content. The boolean field is the new state. **Payload:** `OnPostNsfwUpdateRequest` @@ -209,8 +195,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post being marked or unmarked as a spoiler. -**Use it when:** Your app needs to synchronize labels or presentation with the post's current spoiler state. - **Delivery and safety:** This is a state-change event. The boolean field is the new state. **Payload:** `OnPostSpoilerUpdateRequest` @@ -233,8 +217,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A comment being submitted. -**Use it when:** Your app needs to react as quickly as possible to a new comment. - **Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The comment can later be edited, removed, or deleted. **Payload:** `OnCommentSubmitRequest` @@ -255,8 +237,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created comment after Reddit has allowed time for applicable media safety checks. -**Use it when:** Your workflow benefits from allowing applicable media safety checks more time than the lowest-latency notification permits. - **Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. **Payload:** `OnCommentCreateRequest` @@ -277,8 +257,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A change to a comment's body. -**Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited comment. - **Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `comment` object is a snapshot containing the updated body. **Payload:** `OnCommentUpdateRequest` @@ -300,8 +278,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A report being added to a comment. -**Use it when:** Your app assists with report triage, moderation queues, or report-based automation. - **Delivery and safety:** This is a state-change event. The reported comment can already be removed, changed, or unavailable when your handler runs. **Payload:** `OnCommentReportRequest` @@ -321,8 +297,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A comment being deleted or removed by a user, moderator, or administrator. -**Use it when:** Your app needs to clean up derived data, revoke access, or synchronize deletion state. - **Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted comment body. **Payload:** `OnCommentDeleteRequest` @@ -350,8 +324,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A moderator action recorded in a subreddit's moderation log, such as approving, removing, locking, distinguishing, stickying, or changing flair. -**Use it when:** Your app needs to respond to moderation activity rather than only to the resulting content state. - **Delivery and safety:** This is a moderation event. Its target content can already be unavailable or sanitized when your handler runs. **Payload:** `OnModActionRequest` @@ -376,8 +348,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A message being sent or received in a modmail conversation associated with the installation. -**Use it when:** Your app routes, classifies, or synchronizes modmail activity. - **Delivery and safety:** This is a messaging event. It contains message and conversation metadata, not the message body. **Payload:** `OnModMailRequest` @@ -404,8 +374,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** AutoModerator filtering a post. -**Use it when:** Your app supplements AutoModerator workflows or records why AutoModerator filtered a post. - **Delivery and safety:** This event intentionally represents filtered content. Treat the post and reason as sensitive, untrusted input. **Payload:** `OnAutomoderatorFilterPostRequest` @@ -427,8 +395,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** AutoModerator filtering a comment. -**Use it when:** Your app supplements AutoModerator workflows or records why AutoModerator filtered a comment. - **Delivery and safety:** This event intentionally represents filtered content. Treat the comment and reason as sensitive, untrusted input. **Payload:** `OnAutomoderatorFilterCommentRequest` @@ -452,8 +418,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** The app being installed in a subreddit. -**Use it when:** Your app needs to initialize installation-scoped data or resources. - **Delivery and safety:** This lifecycle event is produced by an installation change, not by an ordinary app upload. **Payload:** `OnAppInstallRequest` @@ -472,8 +436,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A subreddit installation moving to a different version of the app. -**Use it when:** Your app needs to migrate installation-scoped data or enable behavior associated with the newly installed version. - **Delivery and safety:** This lifecycle event is produced when an installation changes version. Uploading or publishing a version does not by itself invoke every installation. **Payload:** `OnAppUpgradeRequest` @@ -494,8 +456,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created comment that mentions the app's username. -**Use it when:** An approved app needs to respond to explicit mentions outside the subreddits where it is ordinarily installed. - **Delivery and safety:** This limited-access global event allows time for applicable [media safety checks](#what-safety-processing-means) on the comment and its parent post. A known match can suppress the event, but ordinary NSFW content can still be present. **Payload:** `OnMentionInCommentCreateRequest` diff --git a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx index 54fb1940..04eea59a 100644 --- a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx +++ b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx @@ -56,8 +56,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post being submitted to a subreddit. -**Use it when:** Your app needs to react as quickly as possible, such as assigning initial metadata or starting a latency-sensitive workflow. - **Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The post can later be edited, removed, or deleted. **Payload:** `OnPostSubmitRequest` @@ -77,8 +75,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created post after Reddit has allowed time for applicable media safety checks. -**Use it when:** Your workflow benefits from allowing applicable media safety checks more time than the lowest-latency notification permits. - **Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. **Payload:** `OnPostCreateRequest` @@ -98,8 +94,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A change to a post's body. -**Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited post. - **Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `post` object is a snapshot containing the updated body. **Payload:** `OnPostUpdateRequest` @@ -120,8 +114,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A report being added to a post. -**Use it when:** Your app assists with report triage, moderation queues, or report-based automation. - **Delivery and safety:** This is a state-change event. The reported post can already be removed, changed, or unavailable when your handler runs. **Payload:** `OnPostReportRequest` @@ -141,8 +133,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post being deleted or removed by a user, moderator, or administrator. -**Use it when:** Your app needs to clean up derived data, revoke access, or synchronize deletion state. - **Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted post body. **Payload:** `OnPostDeleteRequest` @@ -166,8 +156,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post's flair being added, changed, or cleared. -**Use it when:** Your app mirrors flair state or starts automation based on the current post flair. - **Delivery and safety:** This is a state-change event. It is separate from edits to the post body. **Payload:** `OnPostFlairUpdateRequest` @@ -187,8 +175,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post being marked or unmarked as NSFW. -**Use it when:** Your app needs to synchronize access, labels, or presentation with the post's current NSFW state. - **Delivery and safety:** This is a state-change event and can contain NSFW content. The boolean field is the new state. **Payload:** `OnPostNsfwUpdateRequest` @@ -209,8 +195,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A post being marked or unmarked as a spoiler. -**Use it when:** Your app needs to synchronize labels or presentation with the post's current spoiler state. - **Delivery and safety:** This is a state-change event. The boolean field is the new state. **Payload:** `OnPostSpoilerUpdateRequest` @@ -233,8 +217,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A comment being submitted. -**Use it when:** Your app needs to react as quickly as possible to a new comment. - **Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The comment can later be edited, removed, or deleted. **Payload:** `OnCommentSubmitRequest` @@ -255,8 +237,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created comment after Reddit has allowed time for applicable media safety checks. -**Use it when:** Your workflow benefits from allowing applicable media safety checks more time than the lowest-latency notification permits. - **Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. **Payload:** `OnCommentCreateRequest` @@ -277,8 +257,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A change to a comment's body. -**Use it when:** Your app needs to reprocess text, update derived data, or respond to an edited comment. - **Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `comment` object is a snapshot containing the updated body. **Payload:** `OnCommentUpdateRequest` @@ -300,8 +278,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A report being added to a comment. -**Use it when:** Your app assists with report triage, moderation queues, or report-based automation. - **Delivery and safety:** This is a state-change event. The reported comment can already be removed, changed, or unavailable when your handler runs. **Payload:** `OnCommentReportRequest` @@ -321,8 +297,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A comment being deleted or removed by a user, moderator, or administrator. -**Use it when:** Your app needs to clean up derived data, revoke access, or synchronize deletion state. - **Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted comment body. **Payload:** `OnCommentDeleteRequest` @@ -350,8 +324,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A moderator action recorded in a subreddit's moderation log, such as approving, removing, locking, distinguishing, stickying, or changing flair. -**Use it when:** Your app needs to respond to moderation activity rather than only to the resulting content state. - **Delivery and safety:** This is a moderation event. Its target content can already be unavailable or sanitized when your handler runs. **Payload:** `OnModActionRequest` @@ -376,8 +348,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A message being sent or received in a modmail conversation associated with the installation. -**Use it when:** Your app routes, classifies, or synchronizes modmail activity. - **Delivery and safety:** This is a messaging event. It contains message and conversation metadata, not the message body. **Payload:** `OnModMailRequest` @@ -404,8 +374,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** AutoModerator filtering a post. -**Use it when:** Your app supplements AutoModerator workflows or records why AutoModerator filtered a post. - **Delivery and safety:** This event intentionally represents filtered content. Treat the post and reason as sensitive, untrusted input. **Payload:** `OnAutomoderatorFilterPostRequest` @@ -427,8 +395,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** AutoModerator filtering a comment. -**Use it when:** Your app supplements AutoModerator workflows or records why AutoModerator filtered a comment. - **Delivery and safety:** This event intentionally represents filtered content. Treat the comment and reason as sensitive, untrusted input. **Payload:** `OnAutomoderatorFilterCommentRequest` @@ -452,8 +418,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** The app being installed in a subreddit. -**Use it when:** Your app needs to initialize installation-scoped data or resources. - **Delivery and safety:** This lifecycle event is produced by an installation change, not by an ordinary app upload. **Payload:** `OnAppInstallRequest` @@ -472,8 +436,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A subreddit installation moving to a different version of the app. -**Use it when:** Your app needs to migrate installation-scoped data or enable behavior associated with the newly installed version. - **Delivery and safety:** This lifecycle event is produced when an installation changes version. Uploading or publishing a version does not by itself invoke every installation. **Payload:** `OnAppUpgradeRequest` @@ -494,8 +456,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created comment that mentions the app's username. -**Use it when:** An approved app needs to respond to explicit mentions outside the subreddits where it is ordinarily installed. - **Delivery and safety:** This limited-access global event allows time for applicable [media safety checks](#what-safety-processing-means) on the comment and its parent post. A known match can suppress the event, but ordinary NSFW content can still be present. **Payload:** `OnMentionInCommentCreateRequest` From d0cf2de761588ac4855266626ef88c0be018fd6e Mon Sep 17 00:00:00 2001 From: Thomas Wang Date: Wed, 12 Aug 2026 10:50:33 -0400 Subject: [PATCH 4/6] Document safety deadline follow-ups --- docs/capabilities/server/trigger-events.mdx | 10 +++++----- .../capabilities/server/trigger-events.mdx | 10 +++++----- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/capabilities/server/trigger-events.mdx b/docs/capabilities/server/trigger-events.mdx index 04eea59a..f7a7f455 100644 --- a/docs/capabilities/server/trigger-events.mdx +++ b/docs/capabilities/server/trigger-events.mdx @@ -21,7 +21,7 @@ Safety processing for Devvit trigger delivery is not a general moderation review These checks do not certify that content is free of ordinary NSFW material, spam, harassment, or every other policy or community-rule violation. Reddit, AutoModerator, and community moderators can independently remove or change content before or after your handler runs. -Not every event has an applicable media check; most text-only posts and comments do not. Submit events do not wait for an outstanding check, while create events allow time for applicable checks to complete. A create event can still be delivered when no check applies or when a result is unavailable, so delivery is never proof that content is safe or approved. +Not every event has an applicable media check; most text-only posts and comments do not. Submit events do not wait for an outstanding check, while create events allow time for applicable checks to complete. A create event can still be delivered when no check applies or when an applicable check has not completed by the delivery deadline. If a check completes after that deadline and identifies matching content, a corresponding delete event usually follows for apps registered for that delete trigger. Treat the create and delete as separate asynchronous events; the follow-up and its ordering are not guaranteed. Delivery is never proof that content is safe or approved. Safety checking determines whether an event is delivered. Payload sanitization and identity redaction are separate protections that determine what data the event contains. @@ -75,7 +75,7 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created post after Reddit has allowed time for applicable media safety checks. -**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. +**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or an applicable check has not completed by the delivery deadline, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. **Payload:** `OnPostCreateRequest` @@ -86,7 +86,7 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `UserV2` | No | Post author. | | `subreddit` | `SubredditV2` | No | Subreddit where the post was created. | -**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. +**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onPostCreate` is delivered at the safety deadline and a later check identifies matching content, [`onPostDelete`](#onpostdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. **API reference:** [PostCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) @@ -237,7 +237,7 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created comment after Reddit has allowed time for applicable media safety checks. -**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. +**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or an applicable check has not completed by the delivery deadline, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. **Payload:** `OnCommentCreateRequest` @@ -249,7 +249,7 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `post` | `PostV2` | No | Post containing the comment. | | `subreddit` | `SubredditV2` | No | Subreddit where the comment was created. | -**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. +**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onCommentCreate` is delivered at the safety deadline and a later check identifies matching content, [`onCommentDelete`](#oncommentdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. **API reference:** [CommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) diff --git a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx index 04eea59a..f7a7f455 100644 --- a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx +++ b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx @@ -21,7 +21,7 @@ Safety processing for Devvit trigger delivery is not a general moderation review These checks do not certify that content is free of ordinary NSFW material, spam, harassment, or every other policy or community-rule violation. Reddit, AutoModerator, and community moderators can independently remove or change content before or after your handler runs. -Not every event has an applicable media check; most text-only posts and comments do not. Submit events do not wait for an outstanding check, while create events allow time for applicable checks to complete. A create event can still be delivered when no check applies or when a result is unavailable, so delivery is never proof that content is safe or approved. +Not every event has an applicable media check; most text-only posts and comments do not. Submit events do not wait for an outstanding check, while create events allow time for applicable checks to complete. A create event can still be delivered when no check applies or when an applicable check has not completed by the delivery deadline. If a check completes after that deadline and identifies matching content, a corresponding delete event usually follows for apps registered for that delete trigger. Treat the create and delete as separate asynchronous events; the follow-up and its ordering are not guaranteed. Delivery is never proof that content is safe or approved. Safety checking determines whether an event is delivered. Payload sanitization and identity redaction are separate protections that determine what data the event contains. @@ -75,7 +75,7 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created post after Reddit has allowed time for applicable media safety checks. -**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. +**Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or an applicable check has not completed by the delivery deadline, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. **Payload:** `OnPostCreateRequest` @@ -86,7 +86,7 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `UserV2` | No | Post author. | | `subreddit` | `SubredditV2` | No | Subreddit where the post was created. | -**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. +**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onPostCreate` is delivered at the safety deadline and a later check identifies matching content, [`onPostDelete`](#onpostdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. **API reference:** [PostCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) @@ -237,7 +237,7 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Represents:** A newly created comment after Reddit has allowed time for applicable media safety checks. -**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or a result is unavailable, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. +**Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or an applicable check has not completed by the delivery deadline, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. **Payload:** `OnCommentCreateRequest` @@ -249,7 +249,7 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `post` | `PostV2` | No | Post containing the comment. | | `subreddit` | `SubredditV2` | No | Subreddit where the comment was created. | -**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. +**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onCommentCreate` is delivered at the safety deadline and a later check identifies matching content, [`onCommentDelete`](#oncommentdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. **API reference:** [CommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) From 9fe2c673fb17a0794c34da09727bc981e4ece50e Mon Sep 17 00:00:00 2001 From: Thomas Wang Date: Wed, 12 Aug 2026 15:38:43 -0400 Subject: [PATCH 5/6] Make trigger payload types explorable --- docs/capabilities/server/trigger-events.mdx | 272 +++++++++++------- .../capabilities/server/trigger-events.mdx | 272 +++++++++++------- 2 files changed, 332 insertions(+), 212 deletions(-) diff --git a/docs/capabilities/server/trigger-events.mdx b/docs/capabilities/server/trigger-events.mdx index f7a7f455..54f35f62 100644 --- a/docs/capabilities/server/trigger-events.mdx +++ b/docs/capabilities/server/trigger-events.mdx @@ -2,7 +2,7 @@ Use this catalog to choose a trigger and understand the request sent to your endpoint. For configuration and handler examples, see [Triggers](./triggers). -The payload types in this page are exported by `@devvit/web/shared`. The tables describe the top-level JSON fields sent to Devvit Web endpoints. Follow the API reference links for the generated event interfaces, and use your installed package's TypeScript definitions as the source of truth for nested objects. +The request types on this page are exported by `@devvit/web/shared`. Select a linked request type to open its generated schema, or expand **View payload fields** for its top-level fields and optionality. Use your installed package's TypeScript definitions as the source of truth for nested objects. ## Delivery and payload expectations @@ -27,28 +27,28 @@ Safety checking determines whether an event is delivered. Payload sanitization a ## Quick reference -| Trigger key | Represents | Primary payload | Delivery and safety | Details | -| ------------------------------ | --------------------------------------------------- | ----------------------------------------------- | ------------------------------------ | ------------------------------------- | -| `onPostSubmit` | A newly submitted post | Post, author, subreddit | Does not wait for media checks | [View](#onpostsubmit) | -| `onPostCreate` | A newly created post after additional processing | Post, author, subreddit | Allows time for media checks | [View](#onpostcreate) | -| `onPostUpdate` | An edit to a post's body | Post, author, previous body, subreddit | Allows applicable media checks | [View](#onpostupdate) | -| `onPostReport` | A report on a post | Post, reason, subreddit | State-change event | [View](#onpostreport) | -| `onPostDelete` | A post deletion or removal | Post ID, deletion metadata, author, subreddit | State-change event | [View](#onpostdelete) | -| `onPostFlairUpdate` | A post flair change | Post, updater, subreddit | State-change event | [View](#onpostflairupdate) | -| `onPostNsfwUpdate` | A post's NSFW status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostnsfwupdate) | -| `onPostSpoilerUpdate` | A post's spoiler status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostspoilerupdate) | -| `onCommentSubmit` | A newly submitted comment | Comment, author, post, subreddit | Does not wait for media checks | [View](#oncommentsubmit) | -| `onCommentCreate` | A newly created comment after additional processing | Comment, author, post, subreddit | Allows time for media checks | [View](#oncommentcreate) | -| `onCommentUpdate` | An edit to a comment's body | Comment, author, post, previous body, subreddit | Allows applicable media checks | [View](#oncommentupdate) | -| `onCommentReport` | A report on a comment | Comment, reason, subreddit | State-change event | [View](#oncommentreport) | -| `onCommentDelete` | A comment deletion or removal | Comment, post and parent IDs; deletion metadata | State-change event | [View](#oncommentdelete) | -| `onModAction` | An entry in a community's moderation log | Action, moderator, target, subreddit | Moderation event | [View](#onmodaction) | -| `onModMail` | A new modmail message | Message and conversation metadata | Messaging event | [View](#onmodmail) | -| `onAutomoderatorFilterPost` | AutoModerator filtering a post | Post, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfilterpost) | -| `onAutomoderatorFilterComment` | AutoModerator filtering a comment | Comment, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfiltercomment) | -| `onAppInstall` | An app installation in a subreddit | Subreddit, installer | Lifecycle event | [View](#onappinstall) | -| `onAppUpgrade` | An installation moving to a different app version | Subreddit, installer | Lifecycle event | [View](#onappupgrade) | -| `onMentionInCommentCreate` | A new comment that mentions the app username | Comment, author, post, subreddit, mentions | Global; allows time for media checks | [View](#onmentionincommentcreate) | +| Trigger key | Represents | Payload type | Delivery and safety | Details | +| ------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------- | +| `onPostSubmit` | A newly submitted post | [`OnPostSubmitRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSubmit) | Does not wait for media checks | [View](#onpostsubmit) | +| `onPostCreate` | A newly created post after additional processing | [`OnPostCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) | Allows time for media checks | [View](#onpostcreate) | +| `onPostUpdate` | An edit to a post's body | [`OnPostUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostUpdate) | Allows applicable media checks | [View](#onpostupdate) | +| `onPostReport` | A report on a post | [`OnPostReportRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostReport) | State-change event | [View](#onpostreport) | +| `onPostDelete` | A post deletion or removal | [`OnPostDeleteRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostDelete) | State-change event | [View](#onpostdelete) | +| `onPostFlairUpdate` | A post flair change | [`OnPostFlairUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostFlairUpdate) | State-change event | [View](#onpostflairupdate) | +| `onPostNsfwUpdate` | A post's NSFW status changing | [`OnPostNsfwUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostNsfwUpdate) | State-change event | [View](#onpostnsfwupdate) | +| `onPostSpoilerUpdate` | A post's spoiler status changing | [`OnPostSpoilerUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSpoilerUpdate) | State-change event | [View](#onpostspoilerupdate) | +| `onCommentSubmit` | A newly submitted comment | [`OnCommentSubmitRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentSubmit) | Does not wait for media checks | [View](#oncommentsubmit) | +| `onCommentCreate` | A newly created comment after additional processing | [`OnCommentCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) | Allows time for media checks | [View](#oncommentcreate) | +| `onCommentUpdate` | An edit to a comment's body | [`OnCommentUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentUpdate) | Allows applicable media checks | [View](#oncommentupdate) | +| `onCommentReport` | A report on a comment | [`OnCommentReportRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentReport) | State-change event | [View](#oncommentreport) | +| `onCommentDelete` | A comment deletion or removal | [`OnCommentDeleteRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentDelete) | State-change event | [View](#oncommentdelete) | +| `onModAction` | An entry in a community's moderation log | [`OnModActionRequest`](../../api/public-api/type-aliases/ModActionDefinition) | Moderation event | [View](#onmodaction) | +| `onModMail` | A new modmail message | [`OnModMailRequest`](../../api/public-api/type-aliases/ModMailDefinition) | Messaging event | [View](#onmodmail) | +| `onAutomoderatorFilterPost` | AutoModerator filtering a post | [`OnAutomoderatorFilterPostRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterPost) | Filtered-content event | [View](#onautomoderatorfilterpost) | +| `onAutomoderatorFilterComment` | AutoModerator filtering a comment | [`OnAutomoderatorFilterCommentRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterComment) | Filtered-content event | [View](#onautomoderatorfiltercomment) | +| `onAppInstall` | An app installation in a subreddit | [`OnAppInstallRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppInstall) | Lifecycle event | [View](#onappinstall) | +| `onAppUpgrade` | An installation moving to a different app version | [`OnAppUpgradeRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppUpgrade) | Lifecycle event | [View](#onappupgrade) | +| `onMentionInCommentCreate` | A new comment that mentions the app username | [`OnMentionInCommentCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/MentionInCommentCreate) | Global; allows time for media checks | [View](#onmentionincommentcreate) | ## Post events @@ -58,7 +58,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The post can later be edited, removed, or deleted. -**Payload:** `OnPostSubmitRequest` +**Payload:** [`OnPostSubmitRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSubmit) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | --------------------------------------- | @@ -67,9 +70,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `UserV2` | No | Post author. | | `subreddit` | `SubredditV2` | No | Subreddit where the post was submitted. | -**Important behavior:** Do not treat this event as confirmation that the post passed moderation or safety review. If the workflow can wait, prefer [`onPostCreate`](#onpostcreate). +
-**API reference:** [PostSubmit](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSubmit) +**Important behavior:** Do not treat this event as confirmation that the post passed moderation or safety review. If the workflow can wait, prefer [`onPostCreate`](#onpostcreate). ### onPostCreate @@ -77,7 +80,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or an applicable check has not completed by the delivery deadline, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. -**Payload:** `OnPostCreateRequest` +**Payload:** [`OnPostCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | ------------------------------------- | @@ -86,9 +92,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `UserV2` | No | Post author. | | `subreddit` | `SubredditV2` | No | Subreddit where the post was created. | -**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onPostCreate` is delivered at the safety deadline and a later check identifies matching content, [`onPostDelete`](#onpostdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. +
-**API reference:** [PostCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) +**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onPostCreate` is delivered at the safety deadline and a later check identifies matching content, [`onPostDelete`](#onpostdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. ### onPostUpdate @@ -96,7 +102,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `post` object is a snapshot containing the updated body. -**Payload:** `OnPostUpdateRequest` +**Payload:** [`OnPostUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | -------------- | -------------- | -------- | ------------------------------------------------------------------------- | @@ -106,9 +115,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. +
-**API reference:** [PostUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostUpdate) +**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. ### onPostReport @@ -116,7 +125,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event. The reported post can already be removed, changed, or unavailable when your handler runs. -**Payload:** `OnPostReportRequest` +**Payload:** [`OnPostReportRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostReport) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | ---------------------------------------------------------- | @@ -125,9 +137,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | | `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | -**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. +
-**API reference:** [PostReport](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostReport) +**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. ### onPostDelete @@ -135,22 +147,25 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted post body. -**Payload:** `OnPostDeleteRequest` +**Payload:** [`OnPostDeleteRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostDelete) -| Field | Type | Required | Meaning | -| ----------- | ---------------- | -------- | --------------------------------------------------------------- | -| `type` | `"PostDelete"` | Yes | Event discriminator. | -| `postId` | `string` | Yes | Full post ID, such as `t3_...`. | -| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | -| `author` | `UserV2` | No | Post author when available; deleted identities can be redacted. | -| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | -| `source` | `EventSource` | Yes | Actor category associated with the deletion. It can be unknown. | -| `reason` | `DeletionReason` | Yes | Normalized deletion reason. It can be unspecified or unknown. | -| `subreddit` | `SubredditV2` | No | Subreddit that contained the post. | +
+View payload fields -**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. +| Field | Type | Required | Meaning | +| ----------- | -------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------- | +| `type` | `"PostDelete"` | Yes | Event discriminator. | +| `postId` | `string` | Yes | Full post ID, such as `t3_...`. | +| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | +| `author` | `UserV2` | No | Post author when available; deleted identities can be redacted. | +| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | +| `source` | [`EventSource`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource) | Yes | Actor category associated with the deletion. It can be unknown. | +| `reason` | [`DeletionReason`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) | Yes | Normalized deletion reason. It can be unspecified or unknown. | +| `subreddit` | `SubredditV2` | No | Subreddit that contained the post. | + +
-**API reference:** [PostDelete](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostDelete), [EventSource](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource), and [DeletionReason](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) +**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. ### onPostFlairUpdate @@ -158,7 +173,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event. It is separate from edits to the post body. -**Payload:** `OnPostFlairUpdateRequest` +**Payload:** [`OnPostFlairUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostFlairUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ------------------- | -------- | ------------------------------------------ | @@ -167,9 +185,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `UserV2` | No | User who updated the flair when available. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** `author` is the updater, not necessarily the post author. Inspect the flair on `post`; a missing flair can represent a cleared flair. +
-**API reference:** [PostFlairUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostFlairUpdate) +**Important behavior:** `author` is the updater, not necessarily the post author. Inspect the flair on `post`; a missing flair can represent a cleared flair. ### onPostNsfwUpdate @@ -177,7 +195,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event and can contain NSFW content. The boolean field is the new state. -**Payload:** `OnPostNsfwUpdateRequest` +**Payload:** [`OnPostNsfwUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostNsfwUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ------------------ | -------- | ----------------------------------------------- | @@ -187,9 +208,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `isNsfw` | `boolean` | Yes | New NSFW state. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** `author` is the updater, not necessarily the post author. Use `isNsfw` instead of inferring the new state from the event name. +
-**API reference:** [PostNsfwUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostNsfwUpdate) +**Important behavior:** `author` is the updater, not necessarily the post author. Use `isNsfw` instead of inferring the new state from the event name. ### onPostSpoilerUpdate @@ -197,7 +218,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event. The boolean field is the new state. -**Payload:** `OnPostSpoilerUpdateRequest` +**Payload:** [`OnPostSpoilerUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSpoilerUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | --------------------- | -------- | -------------------------------------------------- | @@ -207,9 +231,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `isSpoiler` | `boolean` | Yes | New spoiler state. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** `author` is the updater, not necessarily the post author. Use `isSpoiler` instead of assuming the event only represents enabling the flag. +
-**API reference:** [PostSpoilerUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSpoilerUpdate) +**Important behavior:** `author` is the updater, not necessarily the post author. Use `isSpoiler` instead of assuming the event only represents enabling the flag. ## Comment events @@ -219,7 +243,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The comment can later be edited, removed, or deleted. -**Payload:** `OnCommentSubmitRequest` +**Payload:** [`OnCommentSubmitRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentSubmit) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ----------------- | -------- | ------------------------------------------ | @@ -229,9 +256,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `post` | `PostV2` | No | Post containing the comment. | | `subreddit` | `SubredditV2` | No | Subreddit where the comment was submitted. | -**Important behavior:** Do not treat this event as confirmation that the comment passed moderation or safety review. If the workflow can wait, prefer [`onCommentCreate`](#oncommentcreate). +
-**API reference:** [CommentSubmit](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentSubmit) +**Important behavior:** Do not treat this event as confirmation that the comment passed moderation or safety review. If the workflow can wait, prefer [`onCommentCreate`](#oncommentcreate). ### onCommentCreate @@ -239,7 +266,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or an applicable check has not completed by the delivery deadline, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. -**Payload:** `OnCommentCreateRequest` +**Payload:** [`OnCommentCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ----------------- | -------- | ---------------------------------------- | @@ -249,9 +279,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `post` | `PostV2` | No | Post containing the comment. | | `subreddit` | `SubredditV2` | No | Subreddit where the comment was created. | -**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onCommentCreate` is delivered at the safety deadline and a later check identifies matching content, [`onCommentDelete`](#oncommentdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. +
-**API reference:** [CommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) +**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onCommentCreate` is delivered at the safety deadline and a later check identifies matching content, [`onCommentDelete`](#oncommentdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. ### onCommentUpdate @@ -259,7 +289,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `comment` object is a snapshot containing the updated body. -**Payload:** `OnCommentUpdateRequest` +**Payload:** [`OnCommentUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | -------------- | ----------------- | -------- | -------------------------------------------------------- | @@ -270,9 +303,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | | `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | -**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. +
-**API reference:** [CommentUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentUpdate) +**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. ### onCommentReport @@ -280,7 +313,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event. The reported comment can already be removed, changed, or unavailable when your handler runs. -**Payload:** `OnCommentReportRequest` +**Payload:** [`OnCommentReportRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentReport) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ----------------- | -------- | ---------------------------------------------------------- | @@ -289,9 +325,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | | `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | -**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. +
-**API reference:** [CommentReport](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentReport) +**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. ### onCommentDelete @@ -299,24 +335,27 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted comment body. -**Payload:** `OnCommentDeleteRequest` - -| Field | Type | Required | Meaning | -| ----------- | ----------------- | -------- | ---------------------------------------------------------------------- | -| `type` | `"CommentDelete"` | Yes | Event discriminator. | -| `commentId` | `string` | Yes | Full comment ID, such as `t1_...`. | -| `postId` | `string` | Yes | Full ID of the post containing the comment. | -| `parentId` | `string` | Yes | Full ID of the parent comment, or the post ID for a top-level comment. | -| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | -| `author` | `UserV2` | No | Comment author when available; deleted identities can be redacted. | -| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | -| `source` | `EventSource` | Yes | Actor category associated with the deletion. It can be unknown. | -| `reason` | `DeletionReason` | Yes | Normalized deletion reason. It can be unspecified or unknown. | -| `subreddit` | `SubredditV2` | No | Subreddit that contained the comment. | +**Payload:** [`OnCommentDeleteRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentDelete) -**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. +
+View payload fields -**API reference:** [CommentDelete](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentDelete), [EventSource](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource), and [DeletionReason](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) +| Field | Type | Required | Meaning | +| ----------- | -------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------- | +| `type` | `"CommentDelete"` | Yes | Event discriminator. | +| `commentId` | `string` | Yes | Full comment ID, such as `t1_...`. | +| `postId` | `string` | Yes | Full ID of the post containing the comment. | +| `parentId` | `string` | Yes | Full ID of the parent comment, or the post ID for a top-level comment. | +| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | +| `author` | `UserV2` | No | Comment author when available; deleted identities can be redacted. | +| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | +| `source` | [`EventSource`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource) | Yes | Actor category associated with the deletion. It can be unknown. | +| `reason` | [`DeletionReason`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) | Yes | Normalized deletion reason. It can be unspecified or unknown. | +| `subreddit` | `SubredditV2` | No | Subreddit that contained the comment. | + +
+ +**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. ## Moderation and community events @@ -326,7 +365,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a moderation event. Its target content can already be unavailable or sanitized when your handler runs. -**Payload:** `OnModActionRequest` +**Payload:** [`OnModActionRequest`](../../api/public-api/type-aliases/ModActionDefinition) + +
+View payload fields | Field | Type | Required | Meaning | | --------------- | ------------- | -------- | ----------------------------------------------------- | @@ -340,9 +382,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `targetPost` | `PostV2` | No | Target post for post-related actions. | | `id` | `string` | No | Identifier for the moderation action. | -**Important behavior:** Target fields depend on `action`; never assume a particular target is present. Treat action names as an evolving string set and handle unknown values safely. Moderator and administrator identities can be replaced with masked identities. +
-**API reference:** [ModActionDefinition](../../api/public-api/type-aliases/ModActionDefinition) +**Important behavior:** Target fields depend on `action`; never assume a particular target is present. Treat action names as an evolving string set and handle unknown values safely. Moderator and administrator identities can be replaced with masked identities. ### onModMail @@ -350,7 +392,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a messaging event. It contains message and conversation metadata, not the message body. -**Payload:** `OnModMailRequest` +**Payload:** [`OnModMailRequest`](../../api/public-api/type-aliases/ModMailDefinition) + +
+View payload fields | Field | Type | Required | Meaning | | ----------------------- | ------------- | -------- | --------------------------------------------------------------- | @@ -366,9 +411,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `conversationId` | `string` | Yes | Base36 conversation ID without a thing prefix. | | `messageId` | `string` | Yes | Base36 message ID without a thing prefix. | -**Important behavior:** Fetch the conversation through the Reddit API when your app needs message contents or current conversation state. `destinationSubreddit` is only relevant to conversation types that have one. +
-**API reference:** [ModMailDefinition](../../api/public-api/type-aliases/ModMailDefinition) +**Important behavior:** Fetch the conversation through the Reddit API when your app needs message contents or current conversation state. `destinationSubreddit` is only relevant to conversation types that have one. ### onAutomoderatorFilterPost @@ -376,7 +421,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event intentionally represents filtered content. Treat the post and reason as sensitive, untrusted input. -**Payload:** `OnAutomoderatorFilterPostRequest` +**Payload:** [`OnAutomoderatorFilterPostRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterPost) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | --------------------------- | -------- | ----------------------------------------------------- | @@ -387,9 +435,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onPostDelete` for deletion or removal state. +
-**API reference:** [AutomoderatorFilterPost](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterPost) +**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onPostDelete` for deletion or removal state. ### onAutomoderatorFilterComment @@ -397,7 +445,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event intentionally represents filtered content. Treat the comment and reason as sensitive, untrusted input. -**Payload:** `OnAutomoderatorFilterCommentRequest` +**Payload:** [`OnAutomoderatorFilterCommentRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterComment) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ------------------------------ | -------- | ----------------------------------------------------- | @@ -408,9 +459,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | | `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | -**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onCommentDelete` for deletion or removal state. +
-**API reference:** [AutomoderatorFilterComment](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterComment) +**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onCommentDelete` for deletion or removal state. ## App lifecycle events @@ -420,7 +471,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This lifecycle event is produced by an installation change, not by an ordinary app upload. -**Payload:** `OnAppInstallRequest` +**Payload:** [`OnAppInstallRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppInstall) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | --------------------------------------------------- | @@ -428,9 +482,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit where the app was installed. | | `installer` | `UserV2` | No | User who initiated the installation when available. | -**Important behavior:** Make initialization safe to retry because the event can be delivered more than once. Do not require `installer` to be present. +
-**API reference:** [AppInstall](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppInstall) +**Important behavior:** Make initialization safe to retry because the event can be delivered more than once. Do not require `installer` to be present. ### onAppUpgrade @@ -438,7 +492,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This lifecycle event is produced when an installation changes version. Uploading or publishing a version does not by itself invoke every installation. -**Payload:** `OnAppUpgradeRequest` +**Payload:** [`OnAppUpgradeRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppUpgrade) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | ---------------------------------------------- | @@ -446,9 +503,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit whose installation was upgraded. | | `installer` | `UserV2` | No | User who initiated the upgrade when available. | -**Important behavior:** Make migrations idempotent and track your own schema or migration version. The payload does not contain the previous and new app version numbers. +
-**API reference:** [AppUpgrade](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppUpgrade) +**Important behavior:** Make migrations idempotent and track your own schema or migration version. The payload does not contain the previous and new app version numbers. ## Global events @@ -458,7 +515,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This limited-access global event allows time for applicable [media safety checks](#what-safety-processing-means) on the comment and its parent post. A known match can suppress the event, but ordinary NSFW content can still be present. -**Payload:** `OnMentionInCommentCreateRequest` +**Payload:** [`OnMentionInCommentCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/MentionInCommentCreate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------------------- | -------- | ----------------------------------------------- | @@ -469,6 +529,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | | `mentions` | `Mentions` | No | Parsed username mentions found in the comment. | -**Important behavior:** The event has additional access, profile-installation, subreddit, and playtest requirements. Review [App Mention Triggers](./global-triggers) before using it. +
-**API reference:** [MentionInCommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/MentionInCommentCreate) +**Important behavior:** The event has additional access, profile-installation, subreddit, and playtest requirements. Review [App Mention Triggers](./global-triggers) before using it. diff --git a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx index f7a7f455..54f35f62 100644 --- a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx +++ b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx @@ -2,7 +2,7 @@ Use this catalog to choose a trigger and understand the request sent to your endpoint. For configuration and handler examples, see [Triggers](./triggers). -The payload types in this page are exported by `@devvit/web/shared`. The tables describe the top-level JSON fields sent to Devvit Web endpoints. Follow the API reference links for the generated event interfaces, and use your installed package's TypeScript definitions as the source of truth for nested objects. +The request types on this page are exported by `@devvit/web/shared`. Select a linked request type to open its generated schema, or expand **View payload fields** for its top-level fields and optionality. Use your installed package's TypeScript definitions as the source of truth for nested objects. ## Delivery and payload expectations @@ -27,28 +27,28 @@ Safety checking determines whether an event is delivered. Payload sanitization a ## Quick reference -| Trigger key | Represents | Primary payload | Delivery and safety | Details | -| ------------------------------ | --------------------------------------------------- | ----------------------------------------------- | ------------------------------------ | ------------------------------------- | -| `onPostSubmit` | A newly submitted post | Post, author, subreddit | Does not wait for media checks | [View](#onpostsubmit) | -| `onPostCreate` | A newly created post after additional processing | Post, author, subreddit | Allows time for media checks | [View](#onpostcreate) | -| `onPostUpdate` | An edit to a post's body | Post, author, previous body, subreddit | Allows applicable media checks | [View](#onpostupdate) | -| `onPostReport` | A report on a post | Post, reason, subreddit | State-change event | [View](#onpostreport) | -| `onPostDelete` | A post deletion or removal | Post ID, deletion metadata, author, subreddit | State-change event | [View](#onpostdelete) | -| `onPostFlairUpdate` | A post flair change | Post, updater, subreddit | State-change event | [View](#onpostflairupdate) | -| `onPostNsfwUpdate` | A post's NSFW status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostnsfwupdate) | -| `onPostSpoilerUpdate` | A post's spoiler status changing | Post, updater, new state, subreddit | State-change event | [View](#onpostspoilerupdate) | -| `onCommentSubmit` | A newly submitted comment | Comment, author, post, subreddit | Does not wait for media checks | [View](#oncommentsubmit) | -| `onCommentCreate` | A newly created comment after additional processing | Comment, author, post, subreddit | Allows time for media checks | [View](#oncommentcreate) | -| `onCommentUpdate` | An edit to a comment's body | Comment, author, post, previous body, subreddit | Allows applicable media checks | [View](#oncommentupdate) | -| `onCommentReport` | A report on a comment | Comment, reason, subreddit | State-change event | [View](#oncommentreport) | -| `onCommentDelete` | A comment deletion or removal | Comment, post and parent IDs; deletion metadata | State-change event | [View](#oncommentdelete) | -| `onModAction` | An entry in a community's moderation log | Action, moderator, target, subreddit | Moderation event | [View](#onmodaction) | -| `onModMail` | A new modmail message | Message and conversation metadata | Messaging event | [View](#onmodmail) | -| `onAutomoderatorFilterPost` | AutoModerator filtering a post | Post, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfilterpost) | -| `onAutomoderatorFilterComment` | AutoModerator filtering a comment | Comment, author ID, reason, subreddit | Filtered-content event | [View](#onautomoderatorfiltercomment) | -| `onAppInstall` | An app installation in a subreddit | Subreddit, installer | Lifecycle event | [View](#onappinstall) | -| `onAppUpgrade` | An installation moving to a different app version | Subreddit, installer | Lifecycle event | [View](#onappupgrade) | -| `onMentionInCommentCreate` | A new comment that mentions the app username | Comment, author, post, subreddit, mentions | Global; allows time for media checks | [View](#onmentionincommentcreate) | +| Trigger key | Represents | Payload type | Delivery and safety | Details | +| ------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------- | +| `onPostSubmit` | A newly submitted post | [`OnPostSubmitRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSubmit) | Does not wait for media checks | [View](#onpostsubmit) | +| `onPostCreate` | A newly created post after additional processing | [`OnPostCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) | Allows time for media checks | [View](#onpostcreate) | +| `onPostUpdate` | An edit to a post's body | [`OnPostUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostUpdate) | Allows applicable media checks | [View](#onpostupdate) | +| `onPostReport` | A report on a post | [`OnPostReportRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostReport) | State-change event | [View](#onpostreport) | +| `onPostDelete` | A post deletion or removal | [`OnPostDeleteRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostDelete) | State-change event | [View](#onpostdelete) | +| `onPostFlairUpdate` | A post flair change | [`OnPostFlairUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostFlairUpdate) | State-change event | [View](#onpostflairupdate) | +| `onPostNsfwUpdate` | A post's NSFW status changing | [`OnPostNsfwUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostNsfwUpdate) | State-change event | [View](#onpostnsfwupdate) | +| `onPostSpoilerUpdate` | A post's spoiler status changing | [`OnPostSpoilerUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSpoilerUpdate) | State-change event | [View](#onpostspoilerupdate) | +| `onCommentSubmit` | A newly submitted comment | [`OnCommentSubmitRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentSubmit) | Does not wait for media checks | [View](#oncommentsubmit) | +| `onCommentCreate` | A newly created comment after additional processing | [`OnCommentCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) | Allows time for media checks | [View](#oncommentcreate) | +| `onCommentUpdate` | An edit to a comment's body | [`OnCommentUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentUpdate) | Allows applicable media checks | [View](#oncommentupdate) | +| `onCommentReport` | A report on a comment | [`OnCommentReportRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentReport) | State-change event | [View](#oncommentreport) | +| `onCommentDelete` | A comment deletion or removal | [`OnCommentDeleteRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentDelete) | State-change event | [View](#oncommentdelete) | +| `onModAction` | An entry in a community's moderation log | [`OnModActionRequest`](../../api/public-api/type-aliases/ModActionDefinition) | Moderation event | [View](#onmodaction) | +| `onModMail` | A new modmail message | [`OnModMailRequest`](../../api/public-api/type-aliases/ModMailDefinition) | Messaging event | [View](#onmodmail) | +| `onAutomoderatorFilterPost` | AutoModerator filtering a post | [`OnAutomoderatorFilterPostRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterPost) | Filtered-content event | [View](#onautomoderatorfilterpost) | +| `onAutomoderatorFilterComment` | AutoModerator filtering a comment | [`OnAutomoderatorFilterCommentRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterComment) | Filtered-content event | [View](#onautomoderatorfiltercomment) | +| `onAppInstall` | An app installation in a subreddit | [`OnAppInstallRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppInstall) | Lifecycle event | [View](#onappinstall) | +| `onAppUpgrade` | An installation moving to a different app version | [`OnAppUpgradeRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppUpgrade) | Lifecycle event | [View](#onappupgrade) | +| `onMentionInCommentCreate` | A new comment that mentions the app username | [`OnMentionInCommentCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/MentionInCommentCreate) | Global; allows time for media checks | [View](#onmentionincommentcreate) | ## Post events @@ -58,7 +58,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The post can later be edited, removed, or deleted. -**Payload:** `OnPostSubmitRequest` +**Payload:** [`OnPostSubmitRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSubmit) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | --------------------------------------- | @@ -67,9 +70,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `UserV2` | No | Post author. | | `subreddit` | `SubredditV2` | No | Subreddit where the post was submitted. | -**Important behavior:** Do not treat this event as confirmation that the post passed moderation or safety review. If the workflow can wait, prefer [`onPostCreate`](#onpostcreate). +
-**API reference:** [PostSubmit](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSubmit) +**Important behavior:** Do not treat this event as confirmation that the post passed moderation or safety review. If the workflow can wait, prefer [`onPostCreate`](#onpostcreate). ### onPostCreate @@ -77,7 +80,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** Delivery is intentionally later than `onPostSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or an applicable check has not completed by the delivery deadline, the event can still be delivered. Receiving it does not certify the post as safe, approved, or permanently available. -**Payload:** `OnPostCreateRequest` +**Payload:** [`OnPostCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | ------------------------------------- | @@ -86,9 +92,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `UserV2` | No | Post author. | | `subreddit` | `SubredditV2` | No | Subreddit where the post was created. | -**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onPostCreate` is delivered at the safety deadline and a later check identifies matching content, [`onPostDelete`](#onpostdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. +
-**API reference:** [PostCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostCreate) +**Important behavior:** A single post can produce both `onPostSubmit` and `onPostCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onPostCreate` is delivered at the safety deadline and a later check identifies matching content, [`onPostDelete`](#onpostdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. ### onPostUpdate @@ -96,7 +102,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `post` object is a snapshot containing the updated body. -**Payload:** `OnPostUpdateRequest` +**Payload:** [`OnPostUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | -------------- | -------------- | -------- | ------------------------------------------------------------------------- | @@ -106,9 +115,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. +
-**API reference:** [PostUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostUpdate) +**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. ### onPostReport @@ -116,7 +125,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event. The reported post can already be removed, changed, or unavailable when your handler runs. -**Payload:** `OnPostReportRequest` +**Payload:** [`OnPostReportRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostReport) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | ---------------------------------------------------------- | @@ -125,9 +137,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | | `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | -**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. +
-**API reference:** [PostReport](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostReport) +**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. ### onPostDelete @@ -135,22 +147,25 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted post body. -**Payload:** `OnPostDeleteRequest` +**Payload:** [`OnPostDeleteRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostDelete) -| Field | Type | Required | Meaning | -| ----------- | ---------------- | -------- | --------------------------------------------------------------- | -| `type` | `"PostDelete"` | Yes | Event discriminator. | -| `postId` | `string` | Yes | Full post ID, such as `t3_...`. | -| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | -| `author` | `UserV2` | No | Post author when available; deleted identities can be redacted. | -| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | -| `source` | `EventSource` | Yes | Actor category associated with the deletion. It can be unknown. | -| `reason` | `DeletionReason` | Yes | Normalized deletion reason. It can be unspecified or unknown. | -| `subreddit` | `SubredditV2` | No | Subreddit that contained the post. | +
+View payload fields -**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. +| Field | Type | Required | Meaning | +| ----------- | -------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------- | +| `type` | `"PostDelete"` | Yes | Event discriminator. | +| `postId` | `string` | Yes | Full post ID, such as `t3_...`. | +| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | +| `author` | `UserV2` | No | Post author when available; deleted identities can be redacted. | +| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | +| `source` | [`EventSource`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource) | Yes | Actor category associated with the deletion. It can be unknown. | +| `reason` | [`DeletionReason`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) | Yes | Normalized deletion reason. It can be unspecified or unknown. | +| `subreddit` | `SubredditV2` | No | Subreddit that contained the post. | + +
-**API reference:** [PostDelete](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostDelete), [EventSource](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource), and [DeletionReason](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) +**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. ### onPostFlairUpdate @@ -158,7 +173,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event. It is separate from edits to the post body. -**Payload:** `OnPostFlairUpdateRequest` +**Payload:** [`OnPostFlairUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostFlairUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ------------------- | -------- | ------------------------------------------ | @@ -167,9 +185,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `UserV2` | No | User who updated the flair when available. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** `author` is the updater, not necessarily the post author. Inspect the flair on `post`; a missing flair can represent a cleared flair. +
-**API reference:** [PostFlairUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostFlairUpdate) +**Important behavior:** `author` is the updater, not necessarily the post author. Inspect the flair on `post`; a missing flair can represent a cleared flair. ### onPostNsfwUpdate @@ -177,7 +195,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event and can contain NSFW content. The boolean field is the new state. -**Payload:** `OnPostNsfwUpdateRequest` +**Payload:** [`OnPostNsfwUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostNsfwUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ------------------ | -------- | ----------------------------------------------- | @@ -187,9 +208,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `isNsfw` | `boolean` | Yes | New NSFW state. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** `author` is the updater, not necessarily the post author. Use `isNsfw` instead of inferring the new state from the event name. +
-**API reference:** [PostNsfwUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostNsfwUpdate) +**Important behavior:** `author` is the updater, not necessarily the post author. Use `isNsfw` instead of inferring the new state from the event name. ### onPostSpoilerUpdate @@ -197,7 +218,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event. The boolean field is the new state. -**Payload:** `OnPostSpoilerUpdateRequest` +**Payload:** [`OnPostSpoilerUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSpoilerUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | --------------------- | -------- | -------------------------------------------------- | @@ -207,9 +231,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `isSpoiler` | `boolean` | Yes | New spoiler state. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** `author` is the updater, not necessarily the post author. Use `isSpoiler` instead of assuming the event only represents enabling the flag. +
-**API reference:** [PostSpoilerUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/PostSpoilerUpdate) +**Important behavior:** `author` is the updater, not necessarily the post author. Use `isSpoiler` instead of assuming the event only represents enabling the flag. ## Comment events @@ -219,7 +243,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event favors faster delivery and does not wait for outstanding [media safety checks](#what-safety-processing-means). A known high-severity illegal-content match can still suppress the event. The comment can later be edited, removed, or deleted. -**Payload:** `OnCommentSubmitRequest` +**Payload:** [`OnCommentSubmitRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentSubmit) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ----------------- | -------- | ------------------------------------------ | @@ -229,9 +256,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `post` | `PostV2` | No | Post containing the comment. | | `subreddit` | `SubredditV2` | No | Subreddit where the comment was submitted. | -**Important behavior:** Do not treat this event as confirmation that the comment passed moderation or safety review. If the workflow can wait, prefer [`onCommentCreate`](#oncommentcreate). +
-**API reference:** [CommentSubmit](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentSubmit) +**Important behavior:** Do not treat this event as confirmation that the comment passed moderation or safety review. If the workflow can wait, prefer [`onCommentCreate`](#oncommentcreate). ### onCommentCreate @@ -239,7 +266,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** Delivery is intentionally later than `onCommentSubmit` to allow relevant [media safety checks](#what-safety-processing-means) to complete. A known match can suppress the event. If no check applies or an applicable check has not completed by the delivery deadline, the event can still be delivered. Receiving it does not certify the comment or its parent post as safe, approved, or permanently available. -**Payload:** `OnCommentCreateRequest` +**Payload:** [`OnCommentCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ----------------- | -------- | ---------------------------------------- | @@ -249,9 +279,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `post` | `PostV2` | No | Post containing the comment. | | `subreddit` | `SubredditV2` | No | Subreddit where the comment was created. | -**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onCommentCreate` is delivered at the safety deadline and a later check identifies matching content, [`onCommentDelete`](#oncommentdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. +
-**API reference:** [CommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentCreate) +**Important behavior:** A single comment can produce both `onCommentSubmit` and `onCommentCreate`. Do not register both unless your app has a distinct, idempotent use for each stage. If `onCommentCreate` is delivered at the safety deadline and a later check identifies matching content, [`onCommentDelete`](#oncommentdelete) usually follows when registered. Do not rely on that follow-up or on strict ordering. ### onCommentUpdate @@ -259,7 +289,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** Applicable [media safety checks](#what-safety-processing-means) can delay this event, and a known match can suppress it. The `comment` object is a snapshot containing the updated body. -**Payload:** `OnCommentUpdateRequest` +**Payload:** [`OnCommentUpdateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentUpdate) + +
+View payload fields | Field | Type | Required | Meaning | | -------------- | ----------------- | -------- | -------------------------------------------------------- | @@ -270,9 +303,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | | `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | -**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. +
-**API reference:** [CommentUpdate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentUpdate) +**Important behavior:** Do not use `previousBody` as an audit log or assume it is always populated. Store your own prior value if your app needs a reliable comparison. ### onCommentReport @@ -280,7 +313,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a state-change event. The reported comment can already be removed, changed, or unavailable when your handler runs. -**Payload:** `OnCommentReportRequest` +**Payload:** [`OnCommentReportRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentReport) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ----------------- | -------- | ---------------------------------------------------------- | @@ -289,9 +325,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | | `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | -**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. +
-**API reference:** [CommentReport](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentReport) +**Important behavior:** Reporter identity is intentionally not included. A report event is not a report-count update; fetch current moderation data when counts or current queue state matter. ### onCommentDelete @@ -299,24 +335,27 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event describes a deletion action. It carries identifiers and metadata instead of the deleted comment body. -**Payload:** `OnCommentDeleteRequest` - -| Field | Type | Required | Meaning | -| ----------- | ----------------- | -------- | ---------------------------------------------------------------------- | -| `type` | `"CommentDelete"` | Yes | Event discriminator. | -| `commentId` | `string` | Yes | Full comment ID, such as `t1_...`. | -| `postId` | `string` | Yes | Full ID of the post containing the comment. | -| `parentId` | `string` | Yes | Full ID of the parent comment, or the post ID for a top-level comment. | -| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | -| `author` | `UserV2` | No | Comment author when available; deleted identities can be redacted. | -| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | -| `source` | `EventSource` | Yes | Actor category associated with the deletion. It can be unknown. | -| `reason` | `DeletionReason` | Yes | Normalized deletion reason. It can be unspecified or unknown. | -| `subreddit` | `SubredditV2` | No | Subreddit that contained the comment. | +**Payload:** [`OnCommentDeleteRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentDelete) -**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. +
+View payload fields -**API reference:** [CommentDelete](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/CommentDelete), [EventSource](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource), and [DeletionReason](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) +| Field | Type | Required | Meaning | +| ----------- | -------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------- | +| `type` | `"CommentDelete"` | Yes | Event discriminator. | +| `commentId` | `string` | Yes | Full comment ID, such as `t1_...`. | +| `postId` | `string` | Yes | Full ID of the post containing the comment. | +| `parentId` | `string` | Yes | Full ID of the parent comment, or the post ID for a top-level comment. | +| `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | +| `author` | `UserV2` | No | Comment author when available; deleted identities can be redacted. | +| `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | +| `source` | [`EventSource`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource) | Yes | Actor category associated with the deletion. It can be unknown. | +| `reason` | [`DeletionReason`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) | Yes | Normalized deletion reason. It can be unspecified or unknown. | +| `subreddit` | `SubredditV2` | No | Subreddit that contained the comment. | + +
+ +**Important behavior:** Do not expect the deleted body in this payload. A moderator removal can also produce [`onModAction`](#onmodaction); make cleanup idempotent if you subscribe to both. ## Moderation and community events @@ -326,7 +365,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a moderation event. Its target content can already be unavailable or sanitized when your handler runs. -**Payload:** `OnModActionRequest` +**Payload:** [`OnModActionRequest`](../../api/public-api/type-aliases/ModActionDefinition) + +
+View payload fields | Field | Type | Required | Meaning | | --------------- | ------------- | -------- | ----------------------------------------------------- | @@ -340,9 +382,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `targetPost` | `PostV2` | No | Target post for post-related actions. | | `id` | `string` | No | Identifier for the moderation action. | -**Important behavior:** Target fields depend on `action`; never assume a particular target is present. Treat action names as an evolving string set and handle unknown values safely. Moderator and administrator identities can be replaced with masked identities. +
-**API reference:** [ModActionDefinition](../../api/public-api/type-aliases/ModActionDefinition) +**Important behavior:** Target fields depend on `action`; never assume a particular target is present. Treat action names as an evolving string set and handle unknown values safely. Moderator and administrator identities can be replaced with masked identities. ### onModMail @@ -350,7 +392,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This is a messaging event. It contains message and conversation metadata, not the message body. -**Payload:** `OnModMailRequest` +**Payload:** [`OnModMailRequest`](../../api/public-api/type-aliases/ModMailDefinition) + +
+View payload fields | Field | Type | Required | Meaning | | ----------------------- | ------------- | -------- | --------------------------------------------------------------- | @@ -366,9 +411,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `conversationId` | `string` | Yes | Base36 conversation ID without a thing prefix. | | `messageId` | `string` | Yes | Base36 message ID without a thing prefix. | -**Important behavior:** Fetch the conversation through the Reddit API when your app needs message contents or current conversation state. `destinationSubreddit` is only relevant to conversation types that have one. +
-**API reference:** [ModMailDefinition](../../api/public-api/type-aliases/ModMailDefinition) +**Important behavior:** Fetch the conversation through the Reddit API when your app needs message contents or current conversation state. `destinationSubreddit` is only relevant to conversation types that have one. ### onAutomoderatorFilterPost @@ -376,7 +421,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event intentionally represents filtered content. Treat the post and reason as sensitive, untrusted input. -**Payload:** `OnAutomoderatorFilterPostRequest` +**Payload:** [`OnAutomoderatorFilterPostRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterPost) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | --------------------------- | -------- | ----------------------------------------------------- | @@ -387,9 +435,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | | `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onPostDelete` for deletion or removal state. +
-**API reference:** [AutomoderatorFilterPost](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterPost) +**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onPostDelete` for deletion or removal state. ### onAutomoderatorFilterComment @@ -397,7 +445,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This event intentionally represents filtered content. Treat the comment and reason as sensitive, untrusted input. -**Payload:** `OnAutomoderatorFilterCommentRequest` +**Payload:** [`OnAutomoderatorFilterCommentRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterComment) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | ------------------------------ | -------- | ----------------------------------------------------- | @@ -408,9 +459,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | | `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | -**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onCommentDelete` for deletion or removal state. +
-**API reference:** [AutomoderatorFilterComment](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AutomoderatorFilterComment) +**Important behavior:** This trigger is specific to AutoModerator filtering. Use `onModAction` for broader moderator actions and `onCommentDelete` for deletion or removal state. ## App lifecycle events @@ -420,7 +471,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This lifecycle event is produced by an installation change, not by an ordinary app upload. -**Payload:** `OnAppInstallRequest` +**Payload:** [`OnAppInstallRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppInstall) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | --------------------------------------------------- | @@ -428,9 +482,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit where the app was installed. | | `installer` | `UserV2` | No | User who initiated the installation when available. | -**Important behavior:** Make initialization safe to retry because the event can be delivered more than once. Do not require `installer` to be present. +
-**API reference:** [AppInstall](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppInstall) +**Important behavior:** Make initialization safe to retry because the event can be delivered more than once. Do not require `installer` to be present. ### onAppUpgrade @@ -438,7 +492,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This lifecycle event is produced when an installation changes version. Uploading or publishing a version does not by itself invoke every installation. -**Payload:** `OnAppUpgradeRequest` +**Payload:** [`OnAppUpgradeRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppUpgrade) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------- | -------- | ---------------------------------------------- | @@ -446,9 +503,9 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit whose installation was upgraded. | | `installer` | `UserV2` | No | User who initiated the upgrade when available. | -**Important behavior:** Make migrations idempotent and track your own schema or migration version. The payload does not contain the previous and new app version numbers. +
-**API reference:** [AppUpgrade](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/AppUpgrade) +**Important behavior:** Make migrations idempotent and track your own schema or migration version. The payload does not contain the previous and new app version numbers. ## Global events @@ -458,7 +515,10 @@ Safety checking determines whether an event is delivered. Payload sanitization a **Delivery and safety:** This limited-access global event allows time for applicable [media safety checks](#what-safety-processing-means) on the comment and its parent post. A known match can suppress the event, but ordinary NSFW content can still be present. -**Payload:** `OnMentionInCommentCreateRequest` +**Payload:** [`OnMentionInCommentCreateRequest`](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/MentionInCommentCreate) + +
+View payload fields | Field | Type | Required | Meaning | | ----------- | -------------------------- | -------- | ----------------------------------------------- | @@ -469,6 +529,6 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | | `mentions` | `Mentions` | No | Parsed username mentions found in the comment. | -**Important behavior:** The event has additional access, profile-installation, subreddit, and playtest requirements. Review [App Mention Triggers](./global-triggers) before using it. +
-**API reference:** [MentionInCommentCreate](../../api/public-api/@devvit/namespaces/EventTypes/interfaces/MentionInCommentCreate) +**Important behavior:** The event has additional access, profile-installation, subreddit, and playtest requirements. Review [App Mention Triggers](./global-triggers) before using it. From e417184aec589845d639bcde45d92baf81782579 Mon Sep 17 00:00:00 2001 From: Thomas Wang Date: Wed, 12 Aug 2026 16:22:00 -0400 Subject: [PATCH 6/6] Link nested trigger payload types --- docs/capabilities/server/trigger-events.mdx | 276 +++++++++--------- .../capabilities/server/trigger-events.mdx | 276 +++++++++--------- 2 files changed, 282 insertions(+), 270 deletions(-) diff --git a/docs/capabilities/server/trigger-events.mdx b/docs/capabilities/server/trigger-events.mdx index 54f35f62..c02d94cf 100644 --- a/docs/capabilities/server/trigger-events.mdx +++ b/docs/capabilities/server/trigger-events.mdx @@ -4,6 +4,12 @@ Use this catalog to choose a trigger and understand the request sent to your end The request types on this page are exported by `@devvit/web/shared`. Select a linked request type to open its generated schema, or expand **View payload fields** for its top-level fields and optionality. Use your installed package's TypeScript definitions as the source of truth for nested objects. +[post-v2-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/postv2.d.ts +[comment-v2-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/commentv2.d.ts +[user-v2-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/userv2.d.ts +[subreddit-v2-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/subredditv2.d.ts +[mentions-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/mention.d.ts + ## Delivery and payload expectations - **Delivery is asynchronous.** Reddit state can change between the action and your handler. Fetch the current object when your decision depends on its latest state. @@ -63,12 +69,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | --------------------------------------- | -| `type` | `"PostSubmit"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the submitted post. | -| `author` | `UserV2` | No | Post author. | -| `subreddit` | `SubredditV2` | No | Subreddit where the post was submitted. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | --------------------------------------- | +| `type` | `"PostSubmit"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the submitted post. | +| `author` | [`UserV2`][user-v2-type] | No | Post author. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the post was submitted. |
@@ -85,12 +91,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | ------------------------------------- | -| `type` | `"PostCreate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the created post. | -| `author` | `UserV2` | No | Post author. | -| `subreddit` | `SubredditV2` | No | Subreddit where the post was created. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ------------------------------------- | +| `type` | `"PostCreate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the created post. | +| `author` | [`UserV2`][user-v2-type] | No | Post author. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the post was created. |
@@ -107,13 +113,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| -------------- | -------------- | -------- | ------------------------------------------------------------------------- | -| `type` | `"PostUpdate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the post after the edit. | -| `author` | `UserV2` | No | Post author. This is not necessarily the user who performed every update. | -| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| -------------- | ---------------------------------- | -------- | ------------------------------------------------------------------------- | +| `type` | `"PostUpdate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the post after the edit. | +| `author` | [`UserV2`][user-v2-type] | No | Post author. This is not necessarily the user who performed every update. | +| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -130,12 +136,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | ---------------------------------------------------------- | -| `type` | `"PostReport"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the reported post. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ---------------------------------------------------------- | +| `type` | `"PostReport"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the reported post. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. | +| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. |
@@ -157,11 +163,11 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `type` | `"PostDelete"` | Yes | Event discriminator. | | `postId` | `string` | Yes | Full post ID, such as `t3_...`. | | `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | -| `author` | `UserV2` | No | Post author when available; deleted identities can be redacted. | +| `author` | [`UserV2`][user-v2-type] | No | Post author when available; deleted identities can be redacted. | | `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | | `source` | [`EventSource`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource) | Yes | Actor category associated with the deletion. It can be unknown. | | `reason` | [`DeletionReason`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) | Yes | Normalized deletion reason. It can be unspecified or unknown. | -| `subreddit` | `SubredditV2` | No | Subreddit that contained the post. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit that contained the post. | @@ -178,12 +184,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ------------------- | -------- | ------------------------------------------ | -| `type` | `"PostFlairUpdate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot containing the updated flair. | -| `author` | `UserV2` | No | User who updated the flair when available. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ------------------------------------------ | +| `type` | `"PostFlairUpdate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot containing the updated flair. | +| `author` | [`UserV2`][user-v2-type] | No | User who updated the flair when available. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -200,13 +206,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ------------------ | -------- | ----------------------------------------------- | -| `type` | `"PostNsfwUpdate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the updated post. | -| `author` | `UserV2` | No | User who changed the NSFW state when available. | -| `isNsfw` | `boolean` | Yes | New NSFW state. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ----------------------------------------------- | +| `type` | `"PostNsfwUpdate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the updated post. | +| `author` | [`UserV2`][user-v2-type] | No | User who changed the NSFW state when available. | +| `isNsfw` | `boolean` | Yes | New NSFW state. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -223,13 +229,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | --------------------- | -------- | -------------------------------------------------- | -| `type` | `"PostSpoilerUpdate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the updated post. | -| `author` | `UserV2` | No | User who changed the spoiler state when available. | -| `isSpoiler` | `boolean` | Yes | New spoiler state. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | -------------------------------------------------- | +| `type` | `"PostSpoilerUpdate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the updated post. | +| `author` | [`UserV2`][user-v2-type] | No | User who changed the spoiler state when available. | +| `isSpoiler` | `boolean` | Yes | New spoiler state. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -248,13 +254,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ----------------- | -------- | ------------------------------------------ | -| `type` | `"CommentSubmit"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the submitted comment. | -| `author` | `UserV2` | No | Comment author. | -| `post` | `PostV2` | No | Post containing the comment. | -| `subreddit` | `SubredditV2` | No | Subreddit where the comment was submitted. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ------------------------------------------ | +| `type` | `"CommentSubmit"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the submitted comment. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author. | +| `post` | [`PostV2`][post-v2-type] | No | Post containing the comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the comment was submitted. |
@@ -271,13 +277,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ----------------- | -------- | ---------------------------------------- | -| `type` | `"CommentCreate"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the created comment. | -| `author` | `UserV2` | No | Comment author. | -| `post` | `PostV2` | No | Post containing the comment. | -| `subreddit` | `SubredditV2` | No | Subreddit where the comment was created. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ---------------------------------------- | +| `type` | `"CommentCreate"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the created comment. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author. | +| `post` | [`PostV2`][post-v2-type] | No | Post containing the comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the comment was created. |
@@ -294,14 +300,14 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| -------------- | ----------------- | -------- | -------------------------------------------------------- | -| `type` | `"CommentUpdate"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the comment after the edit. | -| `author` | `UserV2` | No | Comment author. | -| `post` | `PostV2` | No | Post containing the comment. | -| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | +| Field | Type | Required | Meaning | +| -------------- | ---------------------------------- | -------- | -------------------------------------------------------- | +| `type` | `"CommentUpdate"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the comment after the edit. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author. | +| `post` | [`PostV2`][post-v2-type] | No | Post containing the comment. | +| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the comment. |
@@ -318,12 +324,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ----------------- | -------- | ---------------------------------------------------------- | -| `type` | `"CommentReport"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the reported comment. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | -| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ---------------------------------------------------------- | +| `type` | `"CommentReport"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the reported comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the comment. | +| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. |
@@ -347,11 +353,11 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `postId` | `string` | Yes | Full ID of the post containing the comment. | | `parentId` | `string` | Yes | Full ID of the parent comment, or the post ID for a top-level comment. | | `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | -| `author` | `UserV2` | No | Comment author when available; deleted identities can be redacted. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author when available; deleted identities can be redacted. | | `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | | `source` | [`EventSource`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource) | Yes | Actor category associated with the deletion. It can be unknown. | | `reason` | [`DeletionReason`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) | Yes | Normalized deletion reason. It can be unspecified or unknown. | -| `subreddit` | `SubredditV2` | No | Subreddit that contained the comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit that contained the comment. | @@ -370,17 +376,17 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| --------------- | ------------- | -------- | ----------------------------------------------------- | -| `type` | `"ModAction"` | Yes | Event discriminator. | -| `action` | `string` | No | Moderation action name. | -| `actionedAt` | `string` | No | Action time as an ISO 8601 string. | -| `subreddit` | `SubredditV2` | No | Subreddit where the action occurred. | -| `moderator` | `UserV2` | No | Moderator when available; the identity can be masked. | -| `targetUser` | `UserV2` | No | Target user for user-related actions. | -| `targetComment` | `CommentV2` | No | Target comment for comment-related actions. | -| `targetPost` | `PostV2` | No | Target post for post-related actions. | -| `id` | `string` | No | Identifier for the moderation action. | +| Field | Type | Required | Meaning | +| --------------- | ---------------------------------- | -------- | ----------------------------------------------------- | +| `type` | `"ModAction"` | Yes | Event discriminator. | +| `action` | `string` | No | Moderation action name. | +| `actionedAt` | `string` | No | Action time as an ISO 8601 string. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the action occurred. | +| `moderator` | [`UserV2`][user-v2-type] | No | Moderator when available; the identity can be masked. | +| `targetUser` | [`UserV2`][user-v2-type] | No | Target user for user-related actions. | +| `targetComment` | [`CommentV2`][comment-v2-type] | No | Target comment for comment-related actions. | +| `targetPost` | [`PostV2`][post-v2-type] | No | Target post for post-related actions. | +| `id` | `string` | No | Identifier for the moderation action. |
@@ -397,19 +403,19 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------------------- | ------------- | -------- | --------------------------------------------------------------- | -| `type` | `"ModMail"` | Yes | Event discriminator. | -| `messageAuthor` | `UserV2` | No | Message author when available. | -| `createdAt` | `string` | No | Message creation time as an ISO 8601 string. | -| `messageAuthorType` | `string` | Yes | Role used by the author, such as moderator or participant. | -| `conversationState` | `string` | Yes | Current state, such as new, in progress, or archived. | -| `conversationType` | `string` | Yes | Conversation category, such as subreddit-to-user or internal. | -| `isAutoGenerated` | `boolean` | Yes | Whether Reddit or an automated system generated the message. | -| `conversationSubreddit` | `SubredditV2` | No | Subreddit that owns the conversation. | -| `destinationSubreddit` | `SubredditV2` | No | Destination subreddit for subreddit-to-subreddit conversations. | -| `conversationId` | `string` | Yes | Base36 conversation ID without a thing prefix. | -| `messageId` | `string` | Yes | Base36 message ID without a thing prefix. | +| Field | Type | Required | Meaning | +| ----------------------- | ---------------------------------- | -------- | --------------------------------------------------------------- | +| `type` | `"ModMail"` | Yes | Event discriminator. | +| `messageAuthor` | [`UserV2`][user-v2-type] | No | Message author when available. | +| `createdAt` | `string` | No | Message creation time as an ISO 8601 string. | +| `messageAuthorType` | `string` | Yes | Role used by the author, such as moderator or participant. | +| `conversationState` | `string` | Yes | Current state, such as new, in progress, or archived. | +| `conversationType` | `string` | Yes | Conversation category, such as subreddit-to-user or internal. | +| `isAutoGenerated` | `boolean` | Yes | Whether Reddit or an automated system generated the message. | +| `conversationSubreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit that owns the conversation. | +| `destinationSubreddit` | [`SubredditV2`][subreddit-v2-type] | No | Destination subreddit for subreddit-to-subreddit conversations. | +| `conversationId` | `string` | Yes | Base36 conversation ID without a thing prefix. | +| `messageId` | `string` | Yes | Base36 message ID without a thing prefix. |
@@ -426,14 +432,14 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | --------------------------- | -------- | ----------------------------------------------------- | -| `type` | `"AutomoderatorFilterPost"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the filtered post. | -| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | -| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | -| `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | -------------------------------------------------------------------- | +| `type` | `"AutomoderatorFilterPost"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the filtered post. | +| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | +| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | +| `author` | `string` | Yes | Author's user ID as a string, not a [`UserV2`][user-v2-type] object. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -450,14 +456,14 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ------------------------------ | -------- | ----------------------------------------------------- | -| `type` | `"AutomoderatorFilterComment"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the filtered comment. | -| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | -| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | -| `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | -------------------------------------------------------------------- | +| `type` | `"AutomoderatorFilterComment"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the filtered comment. | +| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | +| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | +| `author` | `string` | Yes | Author's user ID as a string, not a [`UserV2`][user-v2-type] object. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the comment. |
@@ -476,11 +482,11 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | --------------------------------------------------- | -| `type` | `"AppInstall"` | Yes | Event discriminator. | -| `subreddit` | `SubredditV2` | No | Subreddit where the app was installed. | -| `installer` | `UserV2` | No | User who initiated the installation when available. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | --------------------------------------------------- | +| `type` | `"AppInstall"` | Yes | Event discriminator. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the app was installed. | +| `installer` | [`UserV2`][user-v2-type] | No | User who initiated the installation when available. |
@@ -497,11 +503,11 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | ---------------------------------------------- | -| `type` | `"AppUpgrade"` | Yes | Event discriminator. | -| `subreddit` | `SubredditV2` | No | Subreddit whose installation was upgraded. | -| `installer` | `UserV2` | No | User who initiated the upgrade when available. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ---------------------------------------------- | +| `type` | `"AppUpgrade"` | Yes | Event discriminator. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit whose installation was upgraded. | +| `installer` | [`UserV2`][user-v2-type] | No | User who initiated the upgrade when available. |
@@ -520,14 +526,14 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------------------- | -------- | ----------------------------------------------- | -| `type` | `"MentionInCommentCreate"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the comment containing the mention. | -| `author` | `UserV2` | No | Comment author. | -| `post` | `PostV2` | No | Post containing the comment. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | -| `mentions` | `Mentions` | No | Parsed username mentions found in the comment. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ----------------------------------------------- | +| `type` | `"MentionInCommentCreate"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the comment containing the mention. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author. | +| `post` | [`PostV2`][post-v2-type] | No | Post containing the comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the comment. | +| `mentions` | [`Mentions`][mentions-type] | No | Parsed username mentions found in the comment. |
diff --git a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx index 54f35f62..c02d94cf 100644 --- a/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx +++ b/versioned_docs/version-0.14/capabilities/server/trigger-events.mdx @@ -4,6 +4,12 @@ Use this catalog to choose a trigger and understand the request sent to your end The request types on this page are exported by `@devvit/web/shared`. Select a linked request type to open its generated schema, or expand **View payload fields** for its top-level fields and optionality. Use your installed package's TypeScript definitions as the source of truth for nested objects. +[post-v2-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/postv2.d.ts +[comment-v2-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/commentv2.d.ts +[user-v2-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/userv2.d.ts +[subreddit-v2-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/subredditv2.d.ts +[mentions-type]: https://unpkg.com/browse/@devvit/protos@0.14.0/json/devvit/reddit/v2alpha/mention.d.ts + ## Delivery and payload expectations - **Delivery is asynchronous.** Reddit state can change between the action and your handler. Fetch the current object when your decision depends on its latest state. @@ -63,12 +69,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | --------------------------------------- | -| `type` | `"PostSubmit"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the submitted post. | -| `author` | `UserV2` | No | Post author. | -| `subreddit` | `SubredditV2` | No | Subreddit where the post was submitted. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | --------------------------------------- | +| `type` | `"PostSubmit"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the submitted post. | +| `author` | [`UserV2`][user-v2-type] | No | Post author. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the post was submitted. |
@@ -85,12 +91,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | ------------------------------------- | -| `type` | `"PostCreate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the created post. | -| `author` | `UserV2` | No | Post author. | -| `subreddit` | `SubredditV2` | No | Subreddit where the post was created. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ------------------------------------- | +| `type` | `"PostCreate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the created post. | +| `author` | [`UserV2`][user-v2-type] | No | Post author. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the post was created. |
@@ -107,13 +113,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| -------------- | -------------- | -------- | ------------------------------------------------------------------------- | -| `type` | `"PostUpdate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the post after the edit. | -| `author` | `UserV2` | No | Post author. This is not necessarily the user who performed every update. | -| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| -------------- | ---------------------------------- | -------- | ------------------------------------------------------------------------- | +| `type` | `"PostUpdate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the post after the edit. | +| `author` | [`UserV2`][user-v2-type] | No | Post author. This is not necessarily the user who performed every update. | +| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -130,12 +136,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | ---------------------------------------------------------- | -| `type` | `"PostReport"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the reported post. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | -| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ---------------------------------------------------------- | +| `type` | `"PostReport"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the reported post. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. | +| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. |
@@ -157,11 +163,11 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `type` | `"PostDelete"` | Yes | Event discriminator. | | `postId` | `string` | Yes | Full post ID, such as `t3_...`. | | `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | -| `author` | `UserV2` | No | Post author when available; deleted identities can be redacted. | +| `author` | [`UserV2`][user-v2-type] | No | Post author when available; deleted identities can be redacted. | | `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | | `source` | [`EventSource`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource) | Yes | Actor category associated with the deletion. It can be unknown. | | `reason` | [`DeletionReason`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) | Yes | Normalized deletion reason. It can be unspecified or unknown. | -| `subreddit` | `SubredditV2` | No | Subreddit that contained the post. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit that contained the post. | @@ -178,12 +184,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ------------------- | -------- | ------------------------------------------ | -| `type` | `"PostFlairUpdate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot containing the updated flair. | -| `author` | `UserV2` | No | User who updated the flair when available. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ------------------------------------------ | +| `type` | `"PostFlairUpdate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot containing the updated flair. | +| `author` | [`UserV2`][user-v2-type] | No | User who updated the flair when available. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -200,13 +206,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ------------------ | -------- | ----------------------------------------------- | -| `type` | `"PostNsfwUpdate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the updated post. | -| `author` | `UserV2` | No | User who changed the NSFW state when available. | -| `isNsfw` | `boolean` | Yes | New NSFW state. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ----------------------------------------------- | +| `type` | `"PostNsfwUpdate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the updated post. | +| `author` | [`UserV2`][user-v2-type] | No | User who changed the NSFW state when available. | +| `isNsfw` | `boolean` | Yes | New NSFW state. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -223,13 +229,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | --------------------- | -------- | -------------------------------------------------- | -| `type` | `"PostSpoilerUpdate"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the updated post. | -| `author` | `UserV2` | No | User who changed the spoiler state when available. | -| `isSpoiler` | `boolean` | Yes | New spoiler state. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | -------------------------------------------------- | +| `type` | `"PostSpoilerUpdate"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the updated post. | +| `author` | [`UserV2`][user-v2-type] | No | User who changed the spoiler state when available. | +| `isSpoiler` | `boolean` | Yes | New spoiler state. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -248,13 +254,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ----------------- | -------- | ------------------------------------------ | -| `type` | `"CommentSubmit"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the submitted comment. | -| `author` | `UserV2` | No | Comment author. | -| `post` | `PostV2` | No | Post containing the comment. | -| `subreddit` | `SubredditV2` | No | Subreddit where the comment was submitted. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ------------------------------------------ | +| `type` | `"CommentSubmit"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the submitted comment. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author. | +| `post` | [`PostV2`][post-v2-type] | No | Post containing the comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the comment was submitted. |
@@ -271,13 +277,13 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ----------------- | -------- | ---------------------------------------- | -| `type` | `"CommentCreate"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the created comment. | -| `author` | `UserV2` | No | Comment author. | -| `post` | `PostV2` | No | Post containing the comment. | -| `subreddit` | `SubredditV2` | No | Subreddit where the comment was created. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ---------------------------------------- | +| `type` | `"CommentCreate"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the created comment. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author. | +| `post` | [`PostV2`][post-v2-type] | No | Post containing the comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the comment was created. |
@@ -294,14 +300,14 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| -------------- | ----------------- | -------- | -------------------------------------------------------- | -| `type` | `"CommentUpdate"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the comment after the edit. | -| `author` | `UserV2` | No | Comment author. | -| `post` | `PostV2` | No | Post containing the comment. | -| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | +| Field | Type | Required | Meaning | +| -------------- | ---------------------------------- | -------- | -------------------------------------------------------- | +| `type` | `"CommentUpdate"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the comment after the edit. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author. | +| `post` | [`PostV2`][post-v2-type] | No | Post containing the comment. | +| `previousBody` | `string` | Yes | Previous body when available; otherwise an empty string. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the comment. |
@@ -318,12 +324,12 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ----------------- | -------- | ---------------------------------------------------------- | -| `type` | `"CommentReport"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the reported comment. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | -| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ---------------------------------------------------------- | +| `type` | `"CommentReport"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the reported comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the comment. | +| `reason` | `string` | Yes | Report reason associated with this event. It can be empty. |
@@ -347,11 +353,11 @@ Safety checking determines whether an event is delivered. Payload sanitization a | `postId` | `string` | Yes | Full ID of the post containing the comment. | | `parentId` | `string` | Yes | Full ID of the parent comment, or the post ID for a top-level comment. | | `deletedAt` | `string` | No | Deletion time as an ISO 8601 string. | -| `author` | `UserV2` | No | Comment author when available; deleted identities can be redacted. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author when available; deleted identities can be redacted. | | `createdAt` | `string` | No | Original creation time as an ISO 8601 string. | | `source` | [`EventSource`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/EventSource) | Yes | Actor category associated with the deletion. It can be unknown. | | `reason` | [`DeletionReason`](../../api/public-api/@devvit/namespaces/EventTypes/enumerations/DeletionReason) | Yes | Normalized deletion reason. It can be unspecified or unknown. | -| `subreddit` | `SubredditV2` | No | Subreddit that contained the comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit that contained the comment. | @@ -370,17 +376,17 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| --------------- | ------------- | -------- | ----------------------------------------------------- | -| `type` | `"ModAction"` | Yes | Event discriminator. | -| `action` | `string` | No | Moderation action name. | -| `actionedAt` | `string` | No | Action time as an ISO 8601 string. | -| `subreddit` | `SubredditV2` | No | Subreddit where the action occurred. | -| `moderator` | `UserV2` | No | Moderator when available; the identity can be masked. | -| `targetUser` | `UserV2` | No | Target user for user-related actions. | -| `targetComment` | `CommentV2` | No | Target comment for comment-related actions. | -| `targetPost` | `PostV2` | No | Target post for post-related actions. | -| `id` | `string` | No | Identifier for the moderation action. | +| Field | Type | Required | Meaning | +| --------------- | ---------------------------------- | -------- | ----------------------------------------------------- | +| `type` | `"ModAction"` | Yes | Event discriminator. | +| `action` | `string` | No | Moderation action name. | +| `actionedAt` | `string` | No | Action time as an ISO 8601 string. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the action occurred. | +| `moderator` | [`UserV2`][user-v2-type] | No | Moderator when available; the identity can be masked. | +| `targetUser` | [`UserV2`][user-v2-type] | No | Target user for user-related actions. | +| `targetComment` | [`CommentV2`][comment-v2-type] | No | Target comment for comment-related actions. | +| `targetPost` | [`PostV2`][post-v2-type] | No | Target post for post-related actions. | +| `id` | `string` | No | Identifier for the moderation action. |
@@ -397,19 +403,19 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------------------- | ------------- | -------- | --------------------------------------------------------------- | -| `type` | `"ModMail"` | Yes | Event discriminator. | -| `messageAuthor` | `UserV2` | No | Message author when available. | -| `createdAt` | `string` | No | Message creation time as an ISO 8601 string. | -| `messageAuthorType` | `string` | Yes | Role used by the author, such as moderator or participant. | -| `conversationState` | `string` | Yes | Current state, such as new, in progress, or archived. | -| `conversationType` | `string` | Yes | Conversation category, such as subreddit-to-user or internal. | -| `isAutoGenerated` | `boolean` | Yes | Whether Reddit or an automated system generated the message. | -| `conversationSubreddit` | `SubredditV2` | No | Subreddit that owns the conversation. | -| `destinationSubreddit` | `SubredditV2` | No | Destination subreddit for subreddit-to-subreddit conversations. | -| `conversationId` | `string` | Yes | Base36 conversation ID without a thing prefix. | -| `messageId` | `string` | Yes | Base36 message ID without a thing prefix. | +| Field | Type | Required | Meaning | +| ----------------------- | ---------------------------------- | -------- | --------------------------------------------------------------- | +| `type` | `"ModMail"` | Yes | Event discriminator. | +| `messageAuthor` | [`UserV2`][user-v2-type] | No | Message author when available. | +| `createdAt` | `string` | No | Message creation time as an ISO 8601 string. | +| `messageAuthorType` | `string` | Yes | Role used by the author, such as moderator or participant. | +| `conversationState` | `string` | Yes | Current state, such as new, in progress, or archived. | +| `conversationType` | `string` | Yes | Conversation category, such as subreddit-to-user or internal. | +| `isAutoGenerated` | `boolean` | Yes | Whether Reddit or an automated system generated the message. | +| `conversationSubreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit that owns the conversation. | +| `destinationSubreddit` | [`SubredditV2`][subreddit-v2-type] | No | Destination subreddit for subreddit-to-subreddit conversations. | +| `conversationId` | `string` | Yes | Base36 conversation ID without a thing prefix. | +| `messageId` | `string` | Yes | Base36 message ID without a thing prefix. |
@@ -426,14 +432,14 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | --------------------------- | -------- | ----------------------------------------------------- | -| `type` | `"AutomoderatorFilterPost"` | Yes | Event discriminator. | -| `post` | `PostV2` | No | Snapshot of the filtered post. | -| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | -| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | -| `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the post. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | -------------------------------------------------------------------- | +| `type` | `"AutomoderatorFilterPost"` | Yes | Event discriminator. | +| `post` | [`PostV2`][post-v2-type] | No | Snapshot of the filtered post. | +| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | +| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | +| `author` | `string` | Yes | Author's user ID as a string, not a [`UserV2`][user-v2-type] object. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the post. |
@@ -450,14 +456,14 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | ------------------------------ | -------- | ----------------------------------------------------- | -| `type` | `"AutomoderatorFilterComment"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the filtered comment. | -| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | -| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | -| `author` | `string` | Yes | Author's user ID as a string, not a `UserV2` object. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | -------------------------------------------------------------------- | +| `type` | `"AutomoderatorFilterComment"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the filtered comment. | +| `removedAt` | `string` | No | Filtering time as an ISO 8601 string. | +| `reason` | `string` | Yes | AutoModerator reason when available; it can be empty. | +| `author` | `string` | Yes | Author's user ID as a string, not a [`UserV2`][user-v2-type] object. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the comment. |
@@ -476,11 +482,11 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | --------------------------------------------------- | -| `type` | `"AppInstall"` | Yes | Event discriminator. | -| `subreddit` | `SubredditV2` | No | Subreddit where the app was installed. | -| `installer` | `UserV2` | No | User who initiated the installation when available. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | --------------------------------------------------- | +| `type` | `"AppInstall"` | Yes | Event discriminator. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit where the app was installed. | +| `installer` | [`UserV2`][user-v2-type] | No | User who initiated the installation when available. |
@@ -497,11 +503,11 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------- | -------- | ---------------------------------------------- | -| `type` | `"AppUpgrade"` | Yes | Event discriminator. | -| `subreddit` | `SubredditV2` | No | Subreddit whose installation was upgraded. | -| `installer` | `UserV2` | No | User who initiated the upgrade when available. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ---------------------------------------------- | +| `type` | `"AppUpgrade"` | Yes | Event discriminator. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit whose installation was upgraded. | +| `installer` | [`UserV2`][user-v2-type] | No | User who initiated the upgrade when available. |
@@ -520,14 +526,14 @@ Safety checking determines whether an event is delivered. Payload sanitization a
View payload fields -| Field | Type | Required | Meaning | -| ----------- | -------------------------- | -------- | ----------------------------------------------- | -| `type` | `"MentionInCommentCreate"` | Yes | Event discriminator. | -| `comment` | `CommentV2` | No | Snapshot of the comment containing the mention. | -| `author` | `UserV2` | No | Comment author. | -| `post` | `PostV2` | No | Post containing the comment. | -| `subreddit` | `SubredditV2` | No | Subreddit containing the comment. | -| `mentions` | `Mentions` | No | Parsed username mentions found in the comment. | +| Field | Type | Required | Meaning | +| ----------- | ---------------------------------- | -------- | ----------------------------------------------- | +| `type` | `"MentionInCommentCreate"` | Yes | Event discriminator. | +| `comment` | [`CommentV2`][comment-v2-type] | No | Snapshot of the comment containing the mention. | +| `author` | [`UserV2`][user-v2-type] | No | Comment author. | +| `post` | [`PostV2`][post-v2-type] | No | Post containing the comment. | +| `subreddit` | [`SubredditV2`][subreddit-v2-type] | No | Subreddit containing the comment. | +| `mentions` | [`Mentions`][mentions-type] | No | Parsed username mentions found in the comment. |