Skip to content

Integrating Help Scout

Auth: OAuth 2.0 · Partner program: not required · Setup time: about 20 minutes · Last verified: 2026-05-23

Help Scout is a shared-inbox / help-desk platform aimed at small teams. The adapter wraps the Mailbox API v2 and surfaces conversations, customers, mailboxes, and users into the canonical customer-support schema.

  • OAuth 2.0 Authorization Code grant. Authorize at https://secure.helpscout.net/authentication/authorizeClientApplication. Exchange via POST to https://api.helpscout.net/v2/oauth2/token.
  • Access tokens last 172800 seconds (2 days). Refresh tokens rotate on every refresh — store the new one each time. A 401 from the API is the canonical “token expired” signal.
  • A Client Credentials flow is also available for internal-use integrations against a single Help Scout account.
  1. A Help Scout account with admin rights at secure.helpscout.net.
  2. A registered application under Your Profile → My Apps. Note the App ID (client id) and App Secret, and register the exact redirect URI.
  1. Open /platforms in the admin UI, filter to Customer Support, click Help Scout.
  2. Fill Configure:
    • clientId — your Help Scout App ID.
    • clientSecret — your Help Scout App Secret.
    • redirectUri — ${PUBLIC_BASE_URL}/auth/customer-support/helpscout/callback.
  3. Enable the adapter.

Help Scout does not enforce OAuth scopes — the issued token inherits the role + permissions of the authorizing user. Have the connecting user be an account owner if you need full Mailbox API access; otherwise the adapter will silently 403 on writes they cannot make in the UI.

Configure under Manage → Webhooks. Help Scout signs each delivery with HMAC-SHA1 (base64) in the X-HelpScout-Signature header — the adapter verifies the secret you supply against the raw body.

Subscribe to convo.*, convo.note.*, convo.reply.*, and customer.* events at minimum.

  • Refresh tokens rotate. Always persist the new refresh_token returned from a refresh call — the previous one is invalidated immediately.
  • Rate limit is account-wide. 400 requests per minute per Mailbox API client, shared across all installed integrations under the same app.
  • No “list everything” endpoint for threads. Pull conversations first, then drill in — the adapter does this in two passes.
  • Webhook signature is SHA-1, not SHA-256. A common bug when porting verification code from other Help Scout-style platforms.