Todoist integration

What it does

The Todoist integration lets your agency run your clients' Todoist accounts from TaskJuice. Workflows can create, update, complete, reopen, move and delete tasks; manage projects, sections, labels and comments; pull completed-task reports; and start the moment something changes in Todoist, through webhooks rather than polling.

Connect a Todoist account

Todoist connections use OAuth through your own Todoist app, so you register that app once and every client connects with one click.

1. Open the Todoist App Management Console and create an app.
2. Add your TaskJuice OAuth redirect URL (shown in TaskJuice under Settings, Integrations, OAuth clients) as the app's OAuth redirect URL.
3. In TaskJuice, add the app's Client ID and Client Secret as a Todoist OAuth client.
4. Open Connections, choose Todoist, click Connect, and approve access while signed in to your client's Todoist account.

To revoke access, open Todoist Integrations settings and remove your app.

Set up webhook triggers

Todoist has no API for creating webhook subscriptions. Webhooks belong to your Todoist app, so you set them up once in the App Management Console:

1. Add a Todoist trigger to a workflow and publish it. TaskJuice shows you the workspace's ingress URL.
2. In the App Management Console, open your app and go to Webhooks.
3. Paste the ingress URL as the Webhook callback URL.
4. Tick the events for the triggers you use (each trigger's event is listed below), then activate the webhook.
5. Copy the app's Client Secret into the trigger's signing secret field.

Todoist signs every delivery with an HMAC-SHA256 digest of the raw body, keyed by your client secret and sent base64-encoded in the X-Todoist-Hmac-SHA256 header. TaskJuice rejects anything that fails the check. Retries reuse the same X-Todoist-Delivery-ID, so a redelivered event runs your workflow once.

Two things to know:

• Webhooks start per user after OAuth. A Todoist account only produces events after it has connected through your app. Todoist also does not fire webhooks for the account that created the app until that account completes the OAuth flow too.
• One app, every connected account. Your app sends events for every client account that authorized it to the same URL. To keep a task or section trigger to one client, pick a Project on the trigger; leave it empty to receive every project.

Triggers

Tasks (optional project filter):

• todoist/task-added: a task is added (item:added).
• todoist/task-updated: a task is edited (item:updated).
• todoist/task-completed: a task is completed (item:completed). Completing a recurring task arrives as item:updated with update_intent item_completed and is routed here as well.
• todoist/task-uncompleted: a completed task is reopened (item:uncompleted).
• todoist/task-deleted: a task is deleted (item:deleted).

Comments:

• todoist/comment-added, todoist/comment-updated, todoist/comment-deleted (note:added, note:updated, note:deleted).

Projects:

• todoist/project-added, todoist/project-updated, todoist/project-deleted, todoist/project-archived, todoist/project-unarchived (project:added, project:updated, project:deleted, project:archived, project:unarchived).

Sections (optional project filter):

• todoist/section-added, todoist/section-updated, todoist/section-deleted, todoist/section-archived, todoist/section-unarchived (section:added, section:updated, section:deleted, section:archived, section:unarchived).

Labels and filters:

• todoist/label-added, todoist/label-updated, todoist/label-deleted (label:added, label:updated, label:deleted).
• todoist/filter-added, todoist/filter-updated, todoist/filter-deleted (filter:added, filter:updated, filter:deleted).

Reminders:

• todoist/reminder-fired: a task reminder fires (reminder:fired).

Actions

Tasks:

• todoist/create-task, todoist/quick-add-task: create a task from fields, or from quick-add text such as Call Sam tomorrow #Client A p1.
• todoist/get-task, todoist/update-task, todoist/delete-task.
• todoist/close-task, todoist/reopen-task: complete or reopen a task. Completing a recurring task moves it to its next date.
• todoist/move-task: move a task to another project, section or parent task.
• todoist/list-tasks, todoist/find-tasks: list active tasks, or find them with a Todoist filter query.
• todoist/list-completed-tasks: list tasks completed in a date window of up to three months, optionally for one project.

Projects:

• todoist/create-project, todoist/get-project, todoist/update-project, todoist/delete-project.
• todoist/archive-project, todoist/unarchive-project.
• todoist/list-projects, todoist/find-projects.
• todoist/get-project-collaborators, todoist/list-collaborators: people on one project, or everyone who shares a project with the account.

Sections, labels, filters and comments:

• todoist/create-section, todoist/get-section, todoist/update-section, todoist/delete-section, todoist/list-sections.
• todoist/create-label, todoist/get-label, todoist/update-label, todoist/delete-label, todoist/list-labels.
• todoist/list-filters: the account's saved filters.
• todoist/add-comment-to-task, todoist/add-comment-to-project, todoist/get-comment, todoist/update-comment, todoist/delete-comment, todoist/list-comments.

Known limitations

• Comments need a paid Todoist plan on the connected account.
• Creating, changing or deleting saved filters, and inviting people to a project, are not available as actions. Todoist only offers them as batched sync commands, which TaskJuice does not send.
• Todoist rate-limits each user token. A 429 response is retried automatically with backoff.
• Webhook deliveries can arrive late or out of order, as Todoist notes in its own documentation. Use a Get action when a workflow needs the current state of a record.