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

# Gusto Webhook Setup Guide

> Configure Gusto to deliver events to StackOne.

## Prerequisites

Before continuing, you should have already completed the following for this connector:

<Steps>
  <Step title="Configure the Connector">
    Enable the connector and set up its connector profile in your project. See <a href="/connect/managing-connectors/overview">Managing Connectors</a>.

    <Columns cols={2}>
      <Card title="Connector Profile" href="/connectors/gusto/guides/connector-profile/oauth-2-0" icon="https://stackone-logos.com/api/gusto/filled/png" horizontal>
        Gusto - OAuth 2.0
      </Card>
    </Columns>
  </Step>

  <Step title="Link an Account">
    Connect an account using <a href="/embed/account-linking/overview">StackOne Hub</a> or <a href="/embed/account-linking/auth-link">Auth Link</a>.

    <Columns cols={2}>
      <Card title="Link Account" href="/connectors/gusto/guides/link-account/oauth-2-0" icon="https://stackone-logos.com/api/gusto/filled/png" horizontal>
        Gusto - OAuth 2.0
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>How webhooks are set up</h2>

  <p>There is no manual webhook setup in Gusto — it is fully automatic. On connection, StackOne calls Gusto's `POST /v1/webhook_subscriptions` endpoint to create one subscription covering all supported resource types, pointing at a Native Webhook URL unique to this connection. StackOne generates and registers this URL for you — there is nothing to copy or paste. Gusto then performs a one-time verification: it sends the subscription's `verification_token` to that URL, and StackOne automatically confirms it via `PUT /v1/webhook_subscriptions/{uuid}/verify`, moving the subscription from `pending` to `verified`. Disconnecting the account deletes the subscription. (Subscription management uses Gusto's system-level access token, obtained from your app's client credentials — no additional configuration is required.)</p>
</section>

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

  <p>Each delivery carries the granular event in the top-level `event_type` field (e.g. `company.provisioned`), the affected resource in `resource_uuid`, and a unix `timestamp`. Events are grouped by resource type below; only the events you enable in StackOne are dispatched.</p>

  <Steps>
    <Step title="Review company and payroll events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired across company lifecycle and payroll processing.</p>

        <ul>
          <li><strong>Company</strong> (`company.*`) — provisioned, deprovisioned, updated, onboarded, approved, suspended, and more.</li>
          <li><strong>Payroll</strong> (`payroll.*`) — created, calculated, submitted, processed, paid, reversed, cancelled, and more.</li>
          <li><strong>PaySchedule</strong> (`pay_schedule.*`) — created, updated.</li>
          <li><strong>ExternalPayroll</strong> (`external_payroll.*`) — created, updated, deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review employee and contractor events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for worker records and their sub-resources.</p>

        <ul>
          <li><strong>Employee</strong> (`employee.*`) — created, updated, onboarded, terminated, rehired, deleted, and more.</li>
          <li><strong>Contractor</strong> (`contractor.*`) — created, updated, onboarded, deactivated, reactivated, deleted.</li>
          <li><strong>ContractorPayment</strong> (`contractor_payment.*`) — created, cancelled.</li>
          <li><strong>ContractorPaymentGroup</strong> (`contractor_payment_group.*`) — created, cancelled.</li>
          <li><strong>HomeAddress</strong> (`employee.home_address.*`) / <strong>WorkAddress</strong> (`employee.work_address.*`) — created, updated, deleted.</li>
          <li><strong>EmployeeJobCompensation</strong> (`employee_job_compensation.*`) — created, updated, deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review benefits, banking, and document events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for benefits, bank accounts, and documents/forms.</p>

        <ul>
          <li><strong>CompanyBenefit</strong> (`company_benefit.*`) / <strong>EmployeeBenefit</strong> (`employee_benefit.*`) — created, updated, deleted.</li>
          <li><strong>BankAccount</strong> (`company.bank_account.*`) — created, updated, deleted.</li>
          <li><strong>FastAchConfig</strong> (`fast_ach_config.*`) — activated, deactivated.</li>
          <li><strong>Document</strong> (`document.*`) / <strong>Form</strong> (`form.*`) — created, updated, signed.</li>
          <li><strong>GeneratedDocument</strong> (`generated_document.*`) — generated, failed.</li>
          <li><strong>Signatory</strong> (`signatory.*`) — created, updated, deleted, marked\_for\_invite.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review location, time-off, and notification events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for locations, time-off requests, and platform notifications.</p>

        <ul>
          <li><strong>Location</strong> (`location.*`) — created, updated.</li>
          <li><strong>TimeOffRequest</strong> (`time_off_request.*`) — created, updated, deleted.</li>
          <li><strong>Notification</strong> (`notification.*`) — platform alerts such as information requests and invalid SSN (created, resolved).</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Understand the delivery format</h2>

  <p>Gusto sends each event as an HTTP POST with a JSON body containing `uuid`, `event_type` (the firing event, e.g. `employee.created`), `entity_type` and `entity_uuid` (the specific record that changed — e.g. an Employee or Payroll), `resource_type` and `resource_uuid` (the owning resource, which is always the Company), and `timestamp` (unix seconds). StackOne routes on `entity_type` and maps `event_type` to the event type, `entity_uuid` to the record id, and `timestamp` to the event time.</p>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Verify delivery authenticity</h2>

  <p>Gusto signs each delivery with an `X-Gusto-Signature` header — an HMAC-SHA256 of the payload computed with your subscription's verification token. StackOne authorizes each delivery using the secret token embedded in the per-connection webhook URL, so no extra configuration is required on your side.</p>
</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.