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

# Toggl Webhook Setup Guide

> Configure Toggl 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="/guides/explore-connectors">Managing Connectors</a>.

    <Columns cols={2}>
      <Card title="Connector Profile" href="/connectors/toggl/guides/connector-profile/api-token" icon="https://stackone-logos.com/api/toggle/filled/png" horizontal>
        Toggl - API Token
      </Card>
    </Columns>
  </Step>

  <Step title="Link an Account">
    Connect an account using <a href="/guides/embedding-stackone-hub">StackOne Hub</a> or <a href="/guides/auth-link">Auth Link</a>.

    <Columns cols={2}>
      <Card title="Link Account" href="/connectors/toggl/guides/link-account/api-token" icon="https://stackone-logos.com/api/toggle/filled/png" horizontal>
        Toggl - API Token
      </Card>
    </Columns>
  </Step>
</Steps>

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

  <p>StackOne creates a Toggl Track Webhooks subscription for you on connect — there is nothing to configure in Toggl and no URL to paste.</p>

  <Steps>
    <Step title="Connect with an account API token">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Connect the account with a Toggl API token that can access the workspace you want events from. StackOne subscribes the account's <strong>default workspace</strong>.</p>
      </div>
    </Step>

    <Step title="Let StackOne provision and validate the subscription">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>On connect, StackOne creates one webhook subscription on the default workspace with a wildcard filter covering every entity and action, then triggers Toggl's PING validation and echoes the validation code automatically so the subscription becomes validated and enabled. Toggl enforces tight per-workspace limits (the Free plan allows 1 webhook and 3 event filters), so StackOne uses a single wildcard subscription to stay within the cap. Only the events you enable in StackOne are dispatched.</p>
      </div>
    </Step>
  </Steps>
</section>

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

  <p>The events below can be enabled for this connection. Each delivered payload carries the entity in `metadata.model` and the action in `metadata.action`; the emitted event type is `<entity>.<action>`.</p>

  <Steps>
    <Step title="Review client events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for clients.</p>

        <ul>
          <li><strong>Client Created</strong> (`client.created`) — Fired when a client is created in the workspace.</li>
          <li><strong>Client Updated</strong> (`client.updated`) — Fired when a client is updated.</li>
          <li><strong>Client Deleted</strong> (`client.deleted`) — Fired when a client is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review project events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for projects.</p>

        <ul>
          <li><strong>Project Created</strong> (`project.created`) — Fired when a project is created.</li>
          <li><strong>Project Updated</strong> (`project.updated`) — Fired when a project is updated.</li>
          <li><strong>Project Deleted</strong> (`project.deleted`) — Fired when a project is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review project group events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for project groups.</p>

        <ul>
          <li><strong>Project Group Created</strong> (`project_group.created`) — Fired when a project group is created.</li>
          <li><strong>Project Group Updated</strong> (`project_group.updated`) — Fired when a project group is updated.</li>
          <li><strong>Project Group Deleted</strong> (`project_group.deleted`) — Fired when a project group is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review project user events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for project memberships.</p>

        <ul>
          <li><strong>Project User Created</strong> (`project_user.created`) — Fired when a user is added to a project.</li>
          <li><strong>Project User Updated</strong> (`project_user.updated`) — Fired when a project membership is updated.</li>
          <li><strong>Project User Deleted</strong> (`project_user.deleted`) — Fired when a user is removed from a project.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review tag events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for tags.</p>

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

    <Step title="Review task events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for tasks.</p>

        <ul>
          <li><strong>Task Created</strong> (`task.created`) — Fired when a task is created.</li>
          <li><strong>Task Updated</strong> (`task.updated`) — Fired when a task is updated.</li>
          <li><strong>Task Deleted</strong> (`task.deleted`) — Fired when a task is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review time entry events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for time entries.</p>

        <ul>
          <li><strong>Time Entry Created</strong> (`time_entry.created`) — Fired when a time entry is created.</li>
          <li><strong>Time Entry Updated</strong> (`time_entry.updated`) — Fired when a time entry is updated.</li>
          <li><strong>Time Entry Deleted</strong> (`time_entry.deleted`) — Fired when a time entry is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review timesheet events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for timesheets.</p>

        <ul>
          <li><strong>Timesheet Created</strong> (`timesheet.created`) — Fired when a timesheet is created.</li>
          <li><strong>Timesheet Updated</strong> (`timesheet.updated`) — Fired when a timesheet is updated.</li>
          <li><strong>Timesheet Deleted</strong> (`timesheet.deleted`) — Fired when a timesheet is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review workspace user events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for workspace memberships.</p>

        <ul>
          <li><strong>Workspace User Created</strong> (`workspace_user.created`) — Fired when a user is added to the workspace.</li>
          <li><strong>Workspace User Updated</strong> (`workspace_user.updated`) — Fired when a workspace membership is updated.</li>
          <li><strong>Workspace User Deleted</strong> (`workspace_user.deleted`) — Fired when a user is removed from the workspace.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review workspace events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for the workspace itself.</p>

        <ul>
          <li><strong>Workspace Updated</strong> (`workspace.updated`) — Fired when workspace settings are updated.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

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

  <p>How Toggl delivers events to StackOne.</p>

  <Steps>
    <Step title="Inspect event payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Toggl sends each event as an HTTP POST with a JSON body containing `metadata` (with `model` set to the entity and `action` set to created, updated, or deleted), `payload` (the full entity object, whose `id` is used as the event id), and `created_at`. Toggl sends one event per request.</p>
      </div>
    </Step>

    <Step title="Handle validation pings">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Toggl validates the callback URL by sending a PING containing a `validation_code`. StackOne echoes it automatically to validate the subscription — no action is needed from you.</p>
      </div>
    </Step>

    <Step title="Note signed deliveries">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Toggl signs each delivery with an HMAC of the payload using the subscription secret StackOne sets at creation. StackOne relies on the unguessable callback URL as the security gate.</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.