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

# Todoist Webhook Setup Guide

> Configure Todoist 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/todoist/guides/connector-profile/oauth-2-0" icon="https://stackone-logos.com/api/todoist/filled/png" horizontal>
        Todoist - OAuth 2.0
      </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/todoist/guides/link-account/oauth-2-0" icon="https://stackone-logos.com/api/todoist/filled/png" horizontal>
        Todoist - OAuth 2.0
      </Card>
    </Columns>
  </Step>
</Steps>

<section data-guide-section data-guide-scopes="">
  <h2>Retrieve the Native Webhook URL</h2>

  <p>StackOne generates a unique Native Webhook URL for this connection, which you paste into your Todoist app's webhook settings.</p>

  <Steps>
    <Step title="Copy the Native Webhook URL">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Open this connection in StackOne and copy the <strong>Native Webhook URL</strong> field. It is unique to this connection and already contains the security token Todoist will call, so keep it secret.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Configure the webhook on your Todoist app</h2>

  <p>Todoist webhooks are set on the OAuth app you created for this connection (the one whose Client ID and Client Secret you entered), in the App Management Console.</p>

  <Steps>
    <Step title="Open your app in the App Management Console">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sign in to Todoist, open the <a href="https://app.todoist.com/app/settings/integrations/app-management" target="_blank" rel="noopener noreferrer">App Management Console</a>, and click the app you use for this connection to open its settings.</p>
      </div>
    </Step>

    <Step title="Configure the Webhooks section">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Scroll to the <strong>Webhooks</strong> section and fill it in.</p>

        <ul>
          <li><strong>Callback URL</strong>: paste the <strong>Native Webhook URL</strong> from this connection.</li>
          <li><strong>Webhook version</strong>: select <strong>Todoist API v1</strong>.</li>
          <li><strong>Webhook Events</strong>: tick the events you want to receive (match the events you enabled in StackOne), then save.</li>
        </ul>
      </div>
    </Step>

    <Step title="Note the verification token">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Todoist signs every delivery with an `X-Todoist-Hmac-SHA256` header computed from your app's <strong>Verification token</strong> (shown in the app settings). No action is needed — StackOne authorizes each delivery by the Todoist user id it maps to a connected account.</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 firing event in `event_name` and the affected entity in `event_data`. Only the events you tick in the app's Webhook Events (and enable in StackOne) are delivered.</p>

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

        <ul>
          <li><strong>Task Added</strong> (`item:added`) — Fired when a task is created.</li>
          <li><strong>Task Updated</strong> (`item:updated`) — Fired when a task is updated.</li>
          <li><strong>Task Completed</strong> (`item:completed`) — Fired when a task is completed.</li>
          <li><strong>Task Uncompleted</strong> (`item:uncompleted`) — Fired when a completed task is reopened.</li>
          <li><strong>Task Deleted</strong> (`item:deleted`) — Fired when a task is deleted.</li>
        </ul>
      </div>
    </Step>

    <Step title="Review comment events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired for comments (Todoist "notes").</p>

        <ul>
          <li><strong>Comment Added</strong> (`note:added`) — Fired when a comment is added.</li>
          <li><strong>Comment Updated</strong> (`note:updated`) — Fired when a comment is updated.</li>
          <li><strong>Comment Deleted</strong> (`note:deleted`) — Fired when a comment 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 Added</strong> (`project:added`) — 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>
          <li><strong>Project Archived</strong> (`project:archived`) — Fired when a project is archived.</li>
          <li><strong>Project Unarchived</strong> (`project:unarchived`) — Fired when a project is unarchived.</li>
        </ul>
      </div>
    </Step>

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

        <ul>
          <li><strong>Section Added</strong> (`section:added`) — Fired when a section is created.</li>
          <li><strong>Section Updated</strong> (`section:updated`) — Fired when a section is updated.</li>
          <li><strong>Section Deleted</strong> (`section:deleted`) — Fired when a section is deleted.</li>
          <li><strong>Section Archived</strong> (`section:archived`) — Fired when a section is archived.</li>
          <li><strong>Section Unarchived</strong> (`section:unarchived`) — Fired when a section is unarchived.</li>
        </ul>
      </div>
    </Step>

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

        <ul>
          <li><strong>Label Added</strong> (`label:added`) — Fired when a label is created.</li>
          <li><strong>Label Updated</strong> (`label:updated`) — Fired when a label is updated.</li>
          <li><strong>Label Deleted</strong> (`label:deleted`) — Fired when a label is deleted.</li>
        </ul>
      </div>
    </Step>

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

        <ul>
          <li><strong>Filter Added</strong> (`filter:added`) — Fired when a filter is created.</li>
          <li><strong>Filter Updated</strong> (`filter:updated`) — Fired when a filter is updated.</li>
          <li><strong>Filter Deleted</strong> (`filter:deleted`) — Fired when a filter is deleted.</li>
        </ul>
      </div>
    </Step>

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

        <ul>
          <li><strong>Reminder Fired</strong> (`reminder:fired`) — Fired when a reminder triggers.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

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

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

  <Steps>
    <Step title="Inspect event payloads">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Todoist sends each event as an HTTP POST with a JSON body containing `event_name` (the firing event, e.g. `item:added`), `user_id` (the Todoist user the event belongs to), `event_data` (the affected entity, whose `id` is used as the event id), `event_data_extra` (present on updates), `initiator` (the user who triggered the event), `version`, and `triggered_at` (ISO 8601 time). One event is sent per request.</p>
      </div>
    </Step>

    <Step title="Understand signed deliveries">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Todoist signs each delivery with an `X-Todoist-Hmac-SHA256` header — a base64-encoded HMAC-SHA256 of the raw request body using your app's Verification token. StackOne resolves and authorizes each delivery by the Todoist user id it maps to a connected account.</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.