> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discourse Webhook Setup Guide

> Configure Discourse to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/discourse#getting-started) on the Discourse connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Automatic webhook subscription</h2>

  <p>StackOne creates and manages the Discourse webhook automatically. When webhook events are enabled for a connected account, StackOne creates one webhook on your forum, subscribed to the events you enable and covering every category. You don't need to configure anything in Discourse.</p>

  <Steps>
    <Step title="Check the API key access">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The webhook is created with the <strong>API Key</strong> and <strong>API Username</strong> of the connected account.</p>

        <ul>
          <li>The API key must have <strong>Scope</strong> set to <strong>Global</strong>. Keys with granular or read-only scopes cannot manage webhooks.</li>
          <li>The <strong>API Username</strong> must belong to an administrator. Discourse rejects webhook requests from moderators and regular users.</li>
        </ul>
      </div>
    </Step>

    <Step title="Enable events in StackOne">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Select the webhook events you want in StackOne. StackOne registers the Discourse webhook with exactly those events. You can view it on your forum at `/admin/api/web_hooks`.</p>
      </div>
    </Step>

    <Step title="Change or remove events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Changing the event selection replaces the StackOne webhook with a new one for the updated event list. Disconnecting the account deletes the webhook, which stops deliveries.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following Discourse events can be enabled. Only events selected in StackOne are included in the webhook subscription — Discourse will not deliver events that are not subscribed. Events from the Solved, Assign, Topic Voting, Chat and Calendar plugins are delivered only when that plugin is enabled on your forum.</p>

  <Steps>
    <Step title="Topic events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to topics, including private message topics.</p>

        <ul>
          <li><strong>Topic Created</strong> (`topic_created`) — Fired when a topic is created, including private message topics</li>
          <li><strong>Topic Edited</strong> (`topic_edited`) — Fired when a topic is edited or its status changes. Status changes arrive as `topic_closed_status_updated`, `topic_archived_status_updated`, `topic_visible_status_updated`, `topic_pinned_status_updated`, `topic_pinned_globally_status_updated` or `topic_autoclosed_status_updated`</li>
          <li><strong>Topic Deleted</strong> (`topic_destroyed`) — Fired when a topic is deleted</li>
          <li><strong>Topic Recovered</strong> (`topic_recovered`) — Fired when a deleted topic is recovered</li>
        </ul>
      </div>
    </Step>

    <Step title="Post events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to posts, replies, and likes, including posts in private messages.</p>

        <ul>
          <li><strong>Post Created</strong> (`post_created`) — Fired when a post or reply is created, including the first post of a new topic and private message posts</li>
          <li><strong>Post Edited</strong> (`post_edited`) — Fired when a post is edited</li>
          <li><strong>Post Deleted</strong> (`post_destroyed`) — Fired when a post is deleted</li>
          <li><strong>Post Recovered</strong> (`post_recovered`) — Fired when a deleted post is recovered</li>
          <li><strong>Post Liked</strong> (`post_liked`) — Fired when a user likes a post</li>
        </ul>
      </div>
    </Step>

    <Step title="User events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to user accounts, sign-ins, and trust levels.</p>

        <ul>
          <li><strong>User Created</strong> (`user_created`) — Fired when a user account is created</li>
          <li><strong>User Updated</strong> (`user_updated`) — Fired when a user profile is updated</li>
          <li><strong>User Logged In</strong> (`user_logged_in`) — Fired when a user logs in</li>
          <li><strong>User Logged Out</strong> (`user_logged_out`) — Fired when a user logs out</li>
          <li><strong>User Confirmed Email</strong> (`user_confirmed_email`) — Fired when a user confirms their email address</li>
          <li><strong>User Approved</strong> (`user_approved`) — Fired when a staff member approves a pending user</li>
          <li><strong>User Suspended</strong> (`user_suspended`) — Fired when a user is suspended</li>
          <li><strong>User Unsuspended</strong> (`user_unsuspended`) — Fired when a user suspension is lifted</li>
          <li><strong>User Anonymized</strong> (`user_anonymized`) — Fired when a user is anonymized</li>
          <li><strong>User Deleted</strong> (`user_destroyed`) — Fired when a user is deleted</li>
          <li><strong>User Promoted</strong> (`user_promoted`) — Fired when a user is promoted to a higher trust level</li>
        </ul>
      </div>
    </Step>

    <Step title="Group events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to groups and group membership.</p>

        <ul>
          <li><strong>Group Created</strong> (`group_created`) — Fired when a group is created</li>
          <li><strong>Group Updated</strong> (`group_updated`) — Fired when a group is updated</li>
          <li><strong>Group Deleted</strong> (`group_destroyed`) — Fired when a group is deleted</li>
          <li><strong>User Added to Group</strong> (`user_added_to_group`) — Fired when a user is added to a group</li>
          <li><strong>User Removed from Group</strong> (`user_removed_from_group`) — Fired when a user is removed from a group</li>
        </ul>
      </div>
    </Step>

    <Step title="Category events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to categories.</p>

        <ul>
          <li><strong>Category Created</strong> (`category_created`) — Fired when a category is created</li>
          <li><strong>Category Updated</strong> (`category_updated`) — Fired when a category is updated</li>
          <li><strong>Category Deleted</strong> (`category_destroyed`) — Fired when a category is deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="Tag events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to tags.</p>

        <ul>
          <li><strong>Tag Created</strong> (`tag_created`) — Fired when a tag is created</li>
          <li><strong>Tag Updated</strong> (`tag_updated`) — Fired when a tag is renamed or updated</li>
          <li><strong>Tag Deleted</strong> (`tag_destroyed`) — Fired when a tag is deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="Badge events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to badges granted to users.</p>

        <ul>
          <li><strong>User Badge Granted</strong> (`user_badge_granted`) — Fired when a badge is granted to a user</li>
          <li><strong>User Badge Revoked</strong> (`user_badge_revoked`) — Fired when a badge is revoked from a user</li>
        </ul>
      </div>
    </Step>

    <Step title="Review queue events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to the review queue, such as flagged posts, queued posts, and users awaiting approval.</p>

        <ul>
          <li><strong>Reviewable Created</strong> (`reviewable_created`) — Fired when an item enters the Discourse review queue, such as a flagged post, a queued post, or a user awaiting approval</li>
          <li><strong>Reviewable Updated</strong> (`reviewable_score_updated`, `reviewable_transitioned_to`) — Fired when a review queue item gets a new score or changes status (approved, rejected, ignored, or deleted)</li>
        </ul>
      </div>
    </Step>

    <Step title="Notification events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to notifications sent to any user on the forum.</p>

        <ul>
          <li><strong>Notification Created</strong> (`notification_created`) — Fired when Discourse creates a notification for any user on the forum</li>
        </ul>
      </div>
    </Step>

    <Step title="Solved plugin events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Delivered only when the Solved plugin is enabled on your forum.</p>

        <ul>
          <li><strong>Solution Accepted</strong> (`accepted_solution`) — Fired when a post is marked as the accepted solution of a topic</li>
          <li><strong>Solution Unaccepted</strong> (`unaccepted_solution`) — Fired when an accepted solution is removed from a topic</li>
        </ul>
      </div>
    </Step>

    <Step title="Assign plugin events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Delivered only when the Assign plugin is enabled on your forum.</p>

        <ul>
          <li><strong>Topic Assigned</strong> (`assigned`) — Fired when a topic or post is assigned to a user or group</li>
          <li><strong>Topic Unassigned</strong> (`unassigned`) — Fired when an assignment is removed from a topic or post</li>
        </ul>
      </div>
    </Step>

    <Step title="Topic Voting plugin events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Delivered only when the Topic Voting plugin is enabled on your forum and voting is turned on for the category.</p>

        <ul>
          <li><strong>Topic Upvoted</strong> (`topic_upvote`) — Fired when a user votes for a topic</li>
          <li><strong>Topic Vote Removed</strong> (`topic_unvote`) — Fired when a user removes their vote from a topic</li>
        </ul>
      </div>
    </Step>

    <Step title="Chat events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Delivered only when chat is enabled on your forum.</p>

        <ul>
          <li><strong>Chat Message Created</strong> (`chat_message_created`) — Fired when a chat message is sent in a Discourse chat channel or direct message</li>
          <li><strong>Chat Message Edited</strong> (`chat_message_edited`) — Fired when a chat message is edited</li>
          <li><strong>Chat Message Deleted</strong> (`chat_message_trashed`) — Fired when a chat message is deleted</li>
          <li><strong>Chat Message Restored</strong> (`chat_message_restored`) — Fired when a deleted chat message is restored</li>
        </ul>
      </div>
    </Step>

    <Step title="Calendar plugin events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Delivered only when the Calendar plugin and its events feature are enabled on your forum.</p>

        <ul>
          <li><strong>Calendar Event Created</strong> (`calendar_event_created`) — Fired when a calendar event is created on a post</li>
          <li><strong>Calendar Event Updated</strong> (`calendar_event_updated`) — Fired when a calendar event is updated</li>
          <li><strong>Calendar Event Deleted</strong> (`calendar_event_destroyed`) — Fired when a calendar event is deleted</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Discourse delivers events to StackOne.</p>

  <Steps>
    <Step title="One event per request">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Discourse sends one event per HTTP POST. The JSON body has a single root key named after the event group, for example `topic` or `post`, and the event name is carried in the `X-Discourse-Event` header, for example `topic_created`. StackOne uses the ID of the changed record as the event ID. Likes, assignments and votes have no ID of their own, so the liked post, assigned topic or voted topic ID is used.</p>
      </div>
    </Step>

    <Step title="Private messages">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Topic and post events also fire for private messages. Check `archetype` on topics, or `topic_archetype` on posts, for the value `private_message` to tell them apart.</p>
      </div>
    </Step>

    <Step title="Signatures and retries">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Each delivery is signed in the `X-Discourse-Event-Signature` header with an HMAC-SHA256 of the body. Discourse does not retry failed deliveries unless the `retry_web_hook_events` site setting is turned on.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.