/config webhook

Fire an HTTP call when a task is completed or reopened — connect TTM to anything.

Webhooks let a task talk to the outside world. Associate one with a task: when that task is completed or reopened, TTM sends an HTTP request you defined. It can go to a CI system, a chat, a spreadsheet automation, or anything else that accepts a call.

By default, only members with the Manage Server permission can use /config webhook, like the rest of /config. See Who can open /config.

Creating a webhook

/config webhook

The command takes a few options:

Option	Required?	Values	Notes
action	Required	view · create · modify · delete	What you want to do.
webhook	Required	a name	The webhook to act on, up to 96 characters.
trigger	Optional	completion · reopen	Omit it to act on both directions at once.

Choosing create (or modify) opens a form with four fields:

HTTP method — GET, POST, PUT or DELETE.
URL — a public https address.
Headers — one Key: value per line.
Body — JSON.

A webhook is really a pair of actions — one for completion, one for reopen — under a single name. That’s what the trigger picks.

The trigger is optional on purpose

Omit it and one command covers both directions. Create sets up completion and reopen with the same configuration: the {{state}} and {{when}} tokens tell the two events apart. View prints both, and delete removes the webhook entirely, with all its actions. Modify pre-fills from the completion action and overwrites both.

Webhooks are a Premium feature, and during the beta they are unlocked for everyone. On the Free plan you can’t create new ones, but the ones created during the beta stay: see What a beta list keeps. Each server can keep up to 25 webhooks. Reached the ceiling? Delete one you no longer use — TTM lists them all in the error.

Tokens

Inside the URL, headers and body you can drop {{ }} tokens that TTM replaces at send time.

Built-in tokens

Token	Value
`{{task}}`	The task text
`{{state}}`	State — completed or reopened
`{{list}}`	The list title
`{{user}}` / `{{user_id}}`	Name / id of whoever toggled the task
`{{when}}`	Date and time (ISO-8601)
`{{guild}}` / `{{guild_id}}`	Server name / id
`{{channel}}` / `{{channel_id}}`	Channel name / id

Free variables — define {{key=value}} anywhere in a task’s text and reference {{key}} in the webhook. Unknown tokens simply resolve to an empty string.

Associating a webhook with a task

Creating a webhook doesn’t wire it to anything yet. Open the list, click Webhook on the second button row until it turns blue, pick the webhook from the selector and then the task. From then on, completing or reopening that task fires the call. Click Webhook until it turns red and pick the task to remove the association.

The association is stored in the task itself, as a reserved token: in Bulk update you’ll see it in front of the task text.

- [] {{wb=deploy}} Ship the release notes

You can move it, copy it onto another task or delete it by hand, exactly like a mention. The token never shows up in the rendered list. A task with the token also needs some text. The Content form of a single task doesn’t show the token, and removes one you type there, telling you. wb is the only reserved key: every other {{key=value}} is a free variable (see Tokens above).

When a webhook fires

A webhook fires only when someone ticks or unticks its task in the check selector, the drop-down menu under the list. In detail:

only the task you picked fires its webhook. The tasks that change with it don’t fire theirs: subtasks ticked in cascade, or a group completed by its last subtask;
Reopen all and Bulk update change many tasks at once and fire no webhook;
the list must be in use, holding one of the places of your plan. How a list takes a place: see How the three places work. A list created during the beta is the exception: its tasks can still be ticked without a place. Their webhooks stay silent until the list takes one. TTM tells you so privately.

When a webhook fails

If the call doesn’t reach its destination, TTM writes a warning in the list’s channel. It names the webhook and the task, then explains the error in one sentence. It also says what to check: the address, the headers, the method, or the server you are calling.

If notifications are off on the server, or TTM can’t post in that channel, the warning reaches only whoever ticked the task.

Example

A POST that announces a completion:

Method: POST
URL:     https://example.com/hooks/ttm
Headers: Content-Type: application/json
Body:
{
  "text": "{{user}} {{state}} \"{{task}}\" in {{list}}",
  "at": "{{when}}"
}

Security

For everyone’s safety, TTM only accepts public https URLs. Internal or non-routable destinations — localhost, private IP ranges, link-local addresses — are blocked. The body must be valid JSON, and every header line must follow the Key: value format.