Help

Back to admin

Webhook Details

Bring tasks into TwoDoo from other tools and send completed wins back out again.

TwoDoo currently supports two webhook directions: an incoming todo webhook for creating or updating weekly todos, and an outgoing status webhook that notifies another tool when a Doo is completed.

Generate the incoming webhook URL in Settings when Weekly Todos mode is on. Add up to 3 outgoing status webhook URLs in Advanced settings if other systems should receive completion updates.

Incoming Todo Webhook

Use this webhook to send tasks from Jira, Make, Zapier, or your own system into TwoDoo.

Endpoint

Method: POST. URL: your own generated /api/webhooks/todos/{token} endpoint from Settings. The token is unique per user.

Behavior

If externalTaskId matches an existing active weekly todo, TwoDoo updates that item. Without externalTaskId, each request creates a new weekly todo. Duplicate webhook calls with the same externalTaskId are ignored for about 10 seconds.

Limits and Requirements

Weekly Todos mode must be enabled. The incoming webhook is limited to 30 requests per minute and 200 per day per user. Repeated abuse can temporarily or permanently disable it.

Accepted Fields

title

Required. The todo title. Maximum 140 characters.

priority

Optional. One of: high, normal, low. Default is normal.

description

Optional. Plain text description. Maximum 1000 characters.

descriptionUrlEncoded

Optional. URL-encoded description text. Useful for Jira when raw description text would break JSON.

descriptionBase64

Optional. Base64-encoded description text. Useful for tools that can encode but cannot JSON-escape safely.

plannedForDate

Optional. Planned date in YYYY-MM-DD format.

externalTaskId

Optional but recommended for syncs. External task ID from the sending system. Maximum 255 characters.

Basic Example

{
  "title": "Plan launch email",
  "priority": "high",
  "description": "Imported from Make.com",
  "plannedForDate": "2026-03-19",
  "externalTaskId": "make-12345"
}

Jira-Friendly Example

If Jira raw descriptions break JSON, send the description as descriptionUrlEncoded instead of description.

{
  "title": "{{issue.summary.left(138)}}",
  "priority": "normal",
  "descriptionUrlEncoded": "{{issue.description.urlEncode()}}",
  "externalTaskId": "{{issue.id}}"
}

Outgoing Todo Status Webhook

This webhook sends a JSON payload to your URL whenever a Doo is completed.

Where It Goes

Set up to 3 valid http or https URLs in Advanced settings. TwoDoo will POST the completion payload to each one after a todo changes to done, gratitude, scheduled, delegated, or eliminated. Each target can also use an optional secret and custom JSON body template.

Header

TwoDoo sends the header X-TwoDoo-Event: todo.status_changed together with a JSON body. If a webhook secret is set, it also sends X-Automation-Webhook-Token for tools like Jira.

Outgoing Fields

event

Always todo.status_changed.

userId

The TwoDoo user ID.

userEmail

The saved email address of that user.

todoId

The ID of the completed todo instance.

sourceUserTodoId

The weekly todo/library item ID if this Doo came from the weekly list. Otherwise null.

externalTaskId

The externalTaskId stored on the weekly todo, if present.

title

The completed todo title.

description

The description stored on that todo, if present.

status

One of: done, gratitude, scheduled, delegated, eliminated.

taskDate

The TwoDoo day on which the completion happened, in YYYY-MM-DD format.

plannedForDate

The optional planned date carried by the weekly todo.

completedAt

Completion timestamp in ISO 8601 format.

isDefault

True when the completed item came from a default/simple task key.

Example Payload

{
  "event": "todo.status_changed",
  "userId": 12,
  "userEmail": "sam@example.com",
  "todoId": 481,
  "sourceUserTodoId": 93,
  "externalTaskId": "jira-12345",
  "title": "Plan launch email",
  "description": "Imported from Jira",
  "status": "done",
  "taskDate": "2026-03-22",
  "plannedForDate": "2026-03-23",
  "completedAt": "2026-03-22T15:18:04+00:00",
  "isDefault": false
}

Created with ❤️ by Sam Steiner