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

# Remote Webhook Setup Guide

> Configure Remote 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/remote#getting-started) on the Remote connector page.

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

  <p>On connection, StackOne calls Remote's `POST /v1/webhook-callbacks` endpoint with your API token to register one webhook callback for this connection, using a delivery URL that carries a secret token. Remote then sends one HTTPS POST per event to that URL, StackOne routes it to your integration, and only the events you enable are dispatched. Disconnecting the account deletes the callback.</p>

  <ul>
    <li>No callback URL to copy, and no verification step to complete.</li>
    <li>Connect with an API token that can read the resources you want events for (Remote webhooks respect the token's permissions).</li>
    <li>Only the events you enable in StackOne are subscribed in Remote and delivered.</li>
  </ul>
</section>

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

  <p>Remote groups events into families. Only the events you enable in StackOne are subscribed in Remote and delivered; each delivery carries the specific `event_type`.</p>

  <Steps>
    <Step title="Review employment events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired through the employment lifecycle — onboarding, probation, hiring, user status, and detail changes.</p>

        <ul>
          <li><strong>Employment Updated</strong> (`employment.updated`) — Fired when an employment record is updated.</li>
          <li><strong>Status Updated</strong> (`employment.status.updated`) — Fired when an employment status is updated.</li>
          <li><strong>Account Updated</strong> (`employment.account.updated`) — Fired when an employment account is updated.</li>
          <li><strong>Details Updated</strong> (`employment.details.updated`) — Fired when employment details are updated.</li>
          <li><strong>Personal Information Updated</strong> (`employment.personal_information.updated`) — Fired when personal information is updated.</li>
          <li><strong>Work Email Updated</strong> (`employment.work_email.updated`) — Fired when the work email is updated.</li>
          <li><strong>Employment Agreement Available</strong> (`employment.employment_agreement.available`) — Fired when an employment agreement becomes available.</li>
          <li><strong>Start Date Changed</strong> (`employment.start_date.changed`) — Fired when the start date changes.</li>
          <li><strong>Benefits Selected</strong> (`employment.benefits.selected`) — Fired when benefits are selected.</li>
          <li><strong>Onboarding Started</strong> (`employment.onboarding.started`) — Fired when onboarding starts.</li>
          <li><strong>Onboarding Completed</strong> (`employment.onboarding.completed`) — Fired when onboarding completes.</li>
          <li><strong>Onboarding Cancelled</strong> (`employment.onboarding.cancelled`) — Fired when onboarding is cancelled.</li>
          <li><strong>Onboarding Task Completed</strong> (`employment.onboarding_task.completed`) — Fired when an onboarding task is completed.</li>
          <li><strong>User Status Initiated</strong> (`employment.user_status.initiated`) — Fired when the user status is initiated.</li>
          <li><strong>User Status Invited</strong> (`employment.user_status.invited`) — Fired when the user is invited.</li>
          <li><strong>User Status Activated</strong> (`employment.user_status.activated`) — Fired when the user status becomes activated.</li>
          <li><strong>User Status Deactivated</strong> (`employment.user_status.deactivated`) — Fired when the user status becomes deactivated.</li>
          <li><strong>Contractor Of Record Termination Initiated</strong> (`employment.contractor_of_record_termination.initiated`) — Fired when a contractor-of-record termination is initiated.</li>
          <li><strong>Contractor Of Record Termination Executed</strong> (`employment.contractor_of_record_termination.executed`) — Fired when a contractor-of-record termination is executed.</li>
          <li><strong>Contractor Of Record Termination Cancelled</strong> (`employment.contractor_of_record_termination.cancelled`) — Fired when a contractor-of-record termination is cancelled.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review time off events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired through a time off request's lifecycle.</p>

        <ul>
          <li><strong>Requested</strong> (`timeoff.requested`) — Fired when time off is requested.</li>
          <li><strong>Approved</strong> (`timeoff.approved`) — Fired when a time off request is approved.</li>
          <li><strong>Declined</strong> (`timeoff.declined`) — Fired when a time off request is declined.</li>
          <li><strong>Cancellation Requested</strong> (`timeoff.cancellation_requested`) — Fired when cancellation of a time off request is requested.</li>
          <li><strong>Canceled</strong> (`timeoff.canceled`) — Fired when a time off request is canceled.</li>
          <li><strong>Date Changed</strong> (`timeoff.date_changed`) — Fired when a time off request's dates change.</li>
          <li><strong>Updated</strong> (`timeoff.updated`) — Fired when a time off request is updated.</li>
          <li><strong>Started</strong> (`timeoff.started`) — Fired when a time off period starts.</li>
          <li><strong>Taken</strong> (`timeoff.taken`) — Fired when time off has been taken.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review expense events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired through an expense's lifecycle.</p>

        <ul>
          <li><strong>Submitted</strong> (`expense.submitted`) — Fired when an expense is submitted.</li>
          <li><strong>Approved</strong> (`expense.approved`) — Fired when an expense is approved.</li>
          <li><strong>Declined</strong> (`expense.declined`) — Fired when an expense is declined.</li>
          <li><strong>Reimbursed</strong> (`expense.reimbursed`) — Fired when an expense is reimbursed.</li>
          <li><strong>Updated</strong> (`expense.updated`) — Fired when an expense is updated.</li>
          <li><strong>Deleted</strong> (`expense.deleted`) — Fired when an expense is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review offboarding events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired as an offboarding progresses.</p>

        <ul>
          <li><strong>Submitted</strong> (`offboarding.submitted`) — Fired when an offboarding is submitted.</li>
          <li><strong>Review Started</strong> (`offboarding.review_started`) — Fired when offboarding review starts.</li>
          <li><strong>Submitted To Payroll</strong> (`offboarding.submitted_to_payroll`) — Fired when an offboarding is submitted to payroll.</li>
          <li><strong>Completed</strong> (`offboarding.completed`) — Fired when an offboarding is completed.</li>
          <li><strong>Done</strong> (`offboarding.done`) — Fired when an offboarding is done.</li>
          <li><strong>Deleted</strong> (`offboarding.deleted`) — Fired when an offboarding is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review company events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for company and account-level changes (managers, ownership, pricing, EOR hiring).</p>

        <ul>
          <li><strong>Activated</strong> (`company.activated`) — Fired when a company is activated.</li>
          <li><strong>Archived</strong> (`company.archived`) — Fired when a company is archived.</li>
          <li><strong>Manager Created</strong> (`company.manager_created`) — Fired when a company manager is created.</li>
          <li><strong>Manager Updated</strong> (`company.manager_updated`) — Fired when a company manager is updated.</li>
          <li><strong>Manager Deleted</strong> (`company.manager_deleted`) — Fired when a company manager is deleted.</li>
          <li><strong>Owner Changed</strong> (`company.owner_changed`) — Fired when a company's owner changes.</li>
          <li><strong>Pricing Plan Updated</strong> (`company.pricing_plan.updated`) — Fired when a company's pricing plan is updated.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review payslip and contract events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Payslip release and contract lifecycle events.</p>

        <ul>
          <li><strong>Payslip Released</strong> (`payslip.released`) — Fired when a payslip is released.</li>
          <li><strong>Contract Termination Date Reached</strong> (`contract.termination_date_reached`) — Fired when a contract's termination date is reached.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

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

  <p>Remote sends each event as a single HTTPS POST with a JSON body (not batched). Every payload has a top-level `event_type` plus the relevant resource identifiers (`employment_id` and/or `company_id`) and event-specific data. StackOne maps `event_type` to the event type and the employment (or company) id to the record id, and passes the full body through as the event data.</p>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery, retries, and signatures</h2>

  <p>Your endpoint should return a 2xx status. Remote signs each delivery with an `X-Remote-Signature` header (an HMAC of the body using the callback's signing key) and retries failed deliveries; delivery history can be inspected and replayed from Remote. StackOne authorizes each delivery using the secret token embedded in the per-connection URL, so no extra configuration is required. Design your integration to handle occasional duplicate deliveries idempotently.</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.