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

# Easyship Webhook Setup Guide

> Configure Easyship 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/easyship/guides/connector-profile/access-token" icon="https://stackone-logos.com/api/easyship/filled/png" horizontal>
        Easyship - Access Token
      </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/easyship/guides/link-account/access-token" icon="https://stackone-logos.com/api/easyship/filled/png" horizontal>
        Easyship - Access Token
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>Subscribe via the StackOne dashboard</h2>

  <p>This connector uses <strong>Programmatic Webhooks</strong>. When you enable webhook events for a connected Easyship account, StackOne automatically registers and activates a webhook subscription in Easyship via the API.</p>

  <Steps>
    <Step title="Select event subscriptions in the dashboard">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>In the StackOne dashboard, open the Easyship connector profile and enable the webhook events you want to receive. See the <strong>Available Webhook Events</strong> section below for the full list.</p>
      </div>
    </Step>

    <Step title="Connect the Easyship account">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>On account connection (or when event subscriptions change), StackOne registers the webhook in Easyship on your behalf using the connected account's API access token. The webhook is created via `POST /2024-09/webhooks` and then activated via `PATCH /2024-09/webhooks/{id}/activate`. Each account receives its own dedicated webhook subscription.</p>
      </div>
    </Step>

    <Step title="Verify delivery">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Trigger a matching change in Easyship (for example, create a test shipment and generate a label) and confirm the event reaches your downstream consumer.</p>

        <ul>
          <li>Easyship signs each delivery with the `X-EASYSHIP-SIGNATURE` header — a JWT signed with HS256 using the webhook's secret key.</li>
          <li>StackOne responds with `200 OK` automatically for all recognised events.</li>
          <li>Easyship retries failed deliveries if the endpoint does not return a `2xx` response.</li>
        </ul>
      </div>
    </Step>

    <Step title="Unsubscribe">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Disconnecting the account or removing all event subscriptions deactivates the StackOne-managed webhook in Easyship, stopping all event deliveries.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available Webhook Events</h2>

  <p>The following Easyship events can be enabled. Only events selected in StackOne are included in the subscription.</p>

  <Steps>
    <Step title="Shipment events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to shipment lifecycle and label generation.</p>

        <ul>
          <li><strong>Shipment Label Created</strong> (`shipment.label.created`) — Fired when a shipping label is successfully generated</li>
          <li><strong>Shipment Label Failed</strong> (`shipment.label.failed`) — Fired when label creation fails</li>
          <li><strong>Shipment Tracking Checkpoint Created</strong> (`shipment.tracking.checkpoints.created`) — Fired when a new tracking checkpoint is recorded</li>
          <li><strong>Shipment Tracking Status Changed</strong> (`shipment.tracking.status.changed`) — Fired when the overall tracking status changes</li>
          <li><strong>Shipment Cancelled</strong> (`shipment.cancelled`) — Fired when a shipment is cancelled</li>
          <li><strong>Shipment Warehouse State Updated</strong> (`shipment.warehouse_state.updated`) — Fired when the warehouse state of a shipment changes</li>
        </ul>
      </div>
    </Step>

    <Step title="Batch events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to batch shipment processing.</p>

        <ul>
          <li><strong>Batch Shipment Processed (First)</strong> (`batch.shipment.processed.first`) — Fired when the first shipment in a batch finishes processing</li>
          <li><strong>Batch Shipment Processed (Last)</strong> (`batch.shipment.processed.last`) — Fired when the final shipment in a batch finishes processing</li>
          <li><strong>Batch Shipment Processed</strong> (`batch.shipment.processed`) — Fired for each individual shipment as it is processed within a batch</li>
        </ul>
      </div>
    </Step>

    <Step title="Account and billing events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to account state, credits, and couriers.</p>

        <ul>
          <li><strong>Credit Balance Low</strong> (`credit.balance.low`) — Fired when the account credit balance falls below the configured threshold</li>
          <li><strong>Company Created</strong> (`company.created`) — Fired when a new company is created (Enterprise accounts only)</li>
          <li><strong>Courier State Changed</strong> (`courier.state.changed`) — Fired when a courier's activation state changes on the account</li>
          <li><strong>OAuth Application Access Revoked</strong> (`oauth_application.access.revoked`) — Fired when OAuth access for an application is revoked</li>
        </ul>
      </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.