> ## 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.

# Help Scout Webhook Setup Guide

> Configure Help Scout 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/helpscout#getting-started) on the Help Scout connector page.

<section data-guide-section data-guide-scopes="">
  <h2>How StackOne manages the webhook</h2>

  <p>StackOne creates and manages the Help Scout webhook automatically. When webhook events are enabled for a connected account, StackOne registers one account-wide webhook labeled <strong>StackOne</strong>, subscribed to the events you select, and deletes it when the account is disconnected. You don't need to create a webhook or copy a Native Webhook URL in Help Scout.</p>

  <ul>
    <li>Only the events selected in StackOne are delivered. Changing the selection replaces the webhook with a new one for the updated event list.</li>
    <li>The webhook covers every inbox in the Help Scout account.</li>
    <li>Some events are only sent when the matching Help Scout feature is in use. The section below on optional events shows how to turn them on.</li>
  </ul>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Check the webhook in Help Scout</h2>

  <p>This is optional. Once events are enabled, you can confirm the webhook StackOne created in Help Scout's Webhooks app.</p>

  <Steps>
    <Step title="Open Help Scout settings">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sign in to your <a href="https://secure.helpscout.net/" target="_blank" rel="noopener noreferrer">Help Scout account</a> and click the gear icon (<strong>Settings</strong>) in the top bar.</p>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-open-settings.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=89d61cd8b84e8457db93df5e849ef65b" alt="The Help Scout dashboard with the Settings gear icon highlighted in the top bar" width="1280" height="800" data-path="connectors/helpscout/images/events-open-settings.png" />
      </div>
    </Step>

    <Step title="Open Apps">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the settings menu, click <strong>Apps</strong> under <strong>Workspace</strong>.</p>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-workspace-apps.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=16ed19e9c9ad87513e1abb43c73b78ce" alt="The Help Scout settings menu with Apps highlighted under Workspace" width="1280" height="800" data-path="connectors/helpscout/images/events-workspace-apps.png" />
      </div>
    </Step>

    <Step title="Open the Webhooks app">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the <strong>Apps Directory</strong>, search for `Webhooks` and click the <strong>Webhooks</strong> app.</p>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-webhooks-app.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=4e06242938ab200fdc05383c4349b061" alt="The Apps Directory filtered to the Webhooks app, with the search box and app card highlighted" width="1280" height="800" data-path="connectors/helpscout/images/events-webhooks-app.png" />
      </div>
    </Step>

    <Step title="Find the StackOne webhook">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The <strong>StackOne</strong> webhook is listed with an <strong>ACTIVE</strong> badge. The app panel on the left shows the plan webhooks need, under <strong>Required:</strong>.</p>

        <ul>
          <li>Don't edit or delete this webhook. StackOne manages it, and deleting it stops events from reaching StackOne.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-webhook-listed.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=5fbee47facefd2e4cd57b2d35e1f96ec" alt="The Webhooks app with the StackOne webhook row and the Required Standard or Plus plan note highlighted" width="1280" height="800" data-path="connectors/helpscout/images/events-webhook-listed.png" />
      </div>
    </Step>

    <Step title="Review the subscribed events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Click <strong>StackOne</strong> to expand it. <strong>Events</strong> shows the events StackOne subscribed to, and no <strong>Inboxes</strong> are selected, so the webhook covers every inbox.</p>

        <ul>
          <li>The <strong>Secret Key</strong> and <strong>Callback URL</strong> are set by StackOne. Keep them private.</li>
          <li>The two AI Answers email events aren't shown in this list, even when they are subscribed.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-webhook-events.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=b0d7cc0c022fda6db1f354ae81e2fcdc" alt="The expanded StackOne webhook with the Events checklist and Inboxes highlighted and the Secret Key and Callback URL hidden" width="1280" height="1260" data-path="connectors/helpscout/images/events-webhook-events.png" />
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Turn on Help Scout features for optional events</h2>

  <p>Most events need nothing beyond the webhook. The events below are only sent when the matching Help Scout feature is turned on, so set up only the ones you plan to use.</p>

  <Steps>
    <Step title="Turn on satisfaction ratings">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The `satisfaction.ratings` event needs ratings turned on for the inbox. In <strong>Settings</strong>, click <strong>Inboxes</strong> under <strong>Workspace</strong> and select the inbox. Click <strong>Satisfaction Ratings</strong>, turn on <strong>Enable satisfaction ratings</strong>, and click <strong>Save</strong>.</p>

        <ul>
          <li>Repeat this for every inbox whose replies should collect ratings.</li>
          <li>Help Scout sends the event a few minutes after the customer rates a reply, with the customer's final rating.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-satisfaction-ratings.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=3763edf0492bf8f38c0f0c871caab7c4" alt="Inbox Satisfaction Ratings settings with the menu item, the Enable satisfaction ratings toggle, and Save highlighted" width="1280" height="800" data-path="connectors/helpscout/images/events-satisfaction-ratings.png" />
      </div>
    </Step>

    <Step title="Add custom fields">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The `convo.custom-fields` event needs custom fields on the inbox. In the inbox settings, click <strong>Custom Fields</strong>, then <strong>New Custom Field</strong>.</p>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-custom-fields.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=564ac1d58035399d2c92512551b6835f" alt="Inbox Custom Fields settings with the menu item and the New Custom Field button highlighted" width="1280" height="800" data-path="connectors/helpscout/images/events-custom-fields.png" />
      </div>
    </Step>

    <Step title="Open Beacons or Messages">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Beacon chat and survey events come from Help Scout Beacon. Click <strong>Tools</strong> in the top bar, then <strong>Beacons</strong> for chat or <strong>Messages</strong> for surveys.</p>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-tools-menu.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=0f3a490b9020abaf41333e0b8773ec57" alt="The Tools menu in the Help Scout top bar with Beacons and Messages highlighted" width="1280" height="800" data-path="connectors/helpscout/images/events-tools-menu.png" />
      </div>
    </Step>

    <Step title="Turn on Beacon chat">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The `beacon.chat.created` and `beacon.chat.customer.replied` events need chat turned on for the Beacon. Open the Beacon, click <strong>Contact</strong>, turn on <strong>Chat</strong>, and click <strong>Save</strong>.</p>

        <ul>
          <li>Beacon only offers chat while a Help Scout user is available to chat. When nobody is available, visitors see the email contact form instead and no chat events are sent.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-beacon-chat.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=a81a6fb04e5ae55365bb1e027ce76049" alt="Beacon Contact settings with the Contact menu item, the Chat toggle, and Save highlighted" width="1280" height="800" data-path="connectors/helpscout/images/events-beacon-chat.png" />
      </div>
    </Step>

    <Step title="Create a survey message">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The `message.survey.response.received` event needs a survey message. On the <strong>Messages</strong> page, click <strong>Create Message</strong>, choose the <strong>NPS®</strong> or <strong>Microsurvey</strong> display type, and click <strong>Create</strong>.</p>

        <ul>
          <li>Messages are shown through Beacon, so the survey must run on a Beacon that is installed on your site or app.</li>
        </ul>

        <img src="https://mintcdn.com/stackone-60/egLCtGzkQpmna7BV/connectors/helpscout/images/events-survey-message.png?fit=max&auto=format&n=egLCtGzkQpmna7BV&q=85&s=00891ee776c64c370bbf83d4d846a4aa" alt="The New Message panel with the NPS and Microsurvey display types and the Create button highlighted" width="1280" height="800" data-path="connectors/helpscout/images/events-survey-message.png" />
      </div>
    </Step>
  </Steps>
</section>

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

  <p>The following Help Scout events can be enabled. Only events selected in StackOne are included in the webhook subscription — Help Scout will not deliver events that are not subscribed.</p>

  <Steps>
    <Step title="Conversation events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to the conversation lifecycle, replies, and notes.</p>

        <ul>
          <li><strong>Conversation Created</strong> (`convo.created`) — Fired when a new conversation is created in a Help Scout inbox</li>
          <li><strong>Conversation Assigned</strong> (`convo.assigned`) — Fired when a Help Scout conversation is assigned to a user</li>
          <li><strong>Conversation Moved</strong> (`convo.moved`) — Fired when a Help Scout conversation is moved to a different inbox</li>
          <li><strong>Conversation Status Updated</strong> (`convo.status`) — Fired when the status of a Help Scout conversation changes (active, pending, closed, or spam)</li>
          <li><strong>Conversation Tags Updated</strong> (`convo.tags`) — Fired when tags are added to or removed from a Help Scout conversation</li>
          <li><strong>Conversation Custom Fields Updated</strong> (`convo.custom-fields`) — Fired when the custom field values on a Help Scout conversation are updated</li>
          <li><strong>Conversation Merged</strong> (`convo.merged`) — Fired when two Help Scout conversations are merged into one</li>
          <li><strong>Customer Reply Created</strong> (`convo.customer.reply.created`) — Fired when a customer adds a reply to a Help Scout conversation</li>
          <li><strong>Agent Reply Created</strong> (`convo.agent.reply.created`) — Fired when a Help Scout user sends a reply on a conversation</li>
          <li><strong>Note Created</strong> (`convo.note.created`) — Fired when a Help Scout user adds an internal note to a conversation</li>
          <li><strong>AI Answers Email Reply Created</strong> (`convo.ai-answers-email.reply.created`) — Fired when Help Scout AI Answers sends an email reply on a conversation</li>
          <li><strong>AI Answers Email Resolution</strong> (`convo.ai-answers-email.resolution`) — Fired when Help Scout AI Answers resolves an email conversation</li>
          <li><strong>Conversation Deleted</strong> (`convo.deleted`) — Fired when a Help Scout conversation is deleted</li>
        </ul>
      </div>
    </Step>

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

        <ul>
          <li><strong>Customer Created</strong> (`customer.created`) — Fired when a new customer profile is created in Help Scout</li>
          <li><strong>Customer Updated</strong> (`customer.updated`) — Fired when a Help Scout customer profile is updated</li>
          <li><strong>Customer Deleted</strong> (`customer.deleted`) — Fired when a Help Scout customer profile is deleted</li>
        </ul>
      </div>
    </Step>

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

        <ul>
          <li><strong>Organization Created</strong> (`organization.created`) — Fired when a Help Scout organization is created</li>
          <li><strong>Organization Updated</strong> (`organization.updated`) — Fired when a Help Scout organization is updated</li>
          <li><strong>Organization Deleted</strong> (`organization.deleted`) — Fired when a Help Scout organization 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 the account's tags.</p>

        <ul>
          <li><strong>Tag Created</strong> (`tag.created`) — Fired when a Help Scout tag is created</li>
          <li><strong>Tag Updated</strong> (`tag.updated`) — Fired when a Help Scout tag is updated</li>
          <li><strong>Tag Deleted</strong> (`tag.deleted`) — Fired when a Help Scout tag is deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="Rating events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to customer satisfaction ratings on replies.</p>

        <ul>
          <li><strong>Satisfaction Rating Received</strong> (`satisfaction.ratings`) — Fired when a customer submits a satisfaction rating on a Help Scout reply</li>
        </ul>
      </div>
    </Step>

    <Step title="Survey events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to Help Scout Messages surveys.</p>

        <ul>
          <li><strong>Survey Response Received</strong> (`message.survey.response.received`) — Fired when a customer responds to a Help Scout Messages survey</li>
        </ul>
      </div>
    </Step>

    <Step title="User events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to Help Scout users.</p>

        <ul>
          <li><strong>User Status Changed</strong> (`user.status.changed`) — Fired when a Help Scout user's availability status changes</li>
        </ul>
      </div>
    </Step>

    <Step title="Beacon chat events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to chats started through a Help Scout Beacon.</p>

        <ul>
          <li><strong>Beacon Chat Created</strong> (`beacon.chat.created`) — Fired when a customer starts a new chat through a Help Scout Beacon</li>
          <li><strong>Beacon Chat Customer Replied</strong> (`beacon.chat.customer.replied`) — Fired when a customer replies in a Help Scout Beacon chat</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

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

  <p>Details of how Help Scout 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>Help Scout sends one event per HTTP POST with a JSON body. The event name is carried only in the `X-HelpScout-Event` header (for example `convo.created`), and the body is the changed record itself. StackOne uses the ID of that record (conversation, customer, organization, tag, rating, user, or chat) as the event ID. Survey responses have no ID of their own, so the responding customer's ID is used. Deleted events contain only the ID of the deleted record.</p>
      </div>
    </Step>

    <Step title="Signatures and retries">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Every delivery is signed in the `X-HelpScout-Signature` header. If a delivery fails, Help Scout retries it up to 10 times with increasing delays, and deactivates the webhook after 10 discarded events.</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.