Интеграция ClickUp и n8n: задачи, статусы, custom fields и защита от дублей ¶

Обновлено: 2026-05-30

Проблема: ClickUp гибкий, но из-за этой гибкости интеграции часто пишут задачи не в тот List, теряют custom fields, создают дубли и не соблюдают правила статусов команды.

Решение: Используйте n8n как слой маршрутизации: определите list_id по типу события, нормализуйте приоритет и due date, проверьте idempotency key, запишите custom fields и обновляйте статус только по разрешённым переходам.

Проблема: почему простая интеграция создаёт дубли и ручной хаос ¶

ClickUp часто становится единым местом для маркетинга, разработки, поддержки и операционки. Но если интеграция просто делает POST create task, в одном List оказываются заявки, баги, счета и внутренние поручения без статусов, владельцев и источников.

Правильная настройка ClickUp и n8n начинается не с API-запроса, а с контракта: какие события превращаются в задачи, какие статусы разрешены, какие custom fields обязательны, кто владелец и как повтор события влияет на уже созданную задачу.

Архитектура workflow для n8n ¶

Для ClickUp критично отделять routing от mapping. Если list_id меняется в нескольких местах workflow, поддержка быстро становится опасной.

Контракт входных данных ¶

{
  "source": "support",
  "event_type": "new_bug_report",
  "entity_id": "ticket-7712",
  "title": "Пользователь не получил письмо после оплаты",
  "description": "Нужно проверить webhook ЮKassa и SMTP",
  "priority": "urgent",
  "team": "support",
  "due_at": "2026-06-01T12:00:00+03:00",
  "customer_url": "https://helpdesk.example.ru/tickets/7712",
  "labels": [
    "payment",
    "email"
  ]
}

Поля event_type и entity_id нужны для routing и дедупликации. Не пытайтесь определять тип задачи по словам в title.

Code Node: нормализация, mapping и guard-условия ¶

const src = $json.body ?? $json;
const eventType = String(src.event_type ?? '').trim().toLowerCase();
const entityId = String(src.entity_id ?? '').trim();
if (!eventType || !entityId) throw new Error('event_type and entity_id are required');
const listMap = { new_bug_report: 'CLICKUP_BUGS_LIST_ID', content_request: 'CLICKUP_CONTENT_LIST_ID', sales_followup: 'CLICKUP_SALES_LIST_ID' };
const listId = listMap[eventType] ?? 'CLICKUP_INBOX_LIST_ID';
const priorityMap = { low: 4, normal: 3, high: 2, urgent: 1 };
const priority = priorityMap[String(src.priority ?? 'normal').toLowerCase()] ?? 3;
const dueAt = src.due_at ? Date.parse(src.due_at) : null;
if (src.due_at && Number.isNaN(dueAt)) throw new Error(`Invalid ClickUp due_at: ${src.due_at}`);
const dedupeKey = `clickup:${eventType}:${entityId}`;
return [{ json: { dedupe_key: dedupeKey, list_id: listId, task: {
  name: String(src.title ?? 'New task').trim().slice(0, 180),
  description: `${src.description ?? ''}\n\nSource: ${src.source ?? 'external'}\nEntity: ${entityId}\nURL: ${src.customer_url ?? ''}`,
  priority,
  due_date: dueAt || undefined,
  tags: Array.isArray(src.labels) ? src.labels.slice(0, 10) : [],
  custom_fields: [{ id: 'external_id_field', value: dedupeKey }, { id: 'source_field', value: String(src.source ?? 'external') }]
}} }];

Готовый workflow JSON: скачать и импортировать ¶

Скачать готовый workflow JSON Скачать тестовый payload

{
  "name": "Nodbot - ClickUp task automation with routing",
  "nodes": [
    {
      "name": "Webhook task input",
      "type": "n8n-nodes-base.webhook",
      "purpose": "Принять событие"
    },
    {
      "name": "Route and normalize ClickUp task",
      "type": "n8n-nodes-base.code",
      "purpose": "Выбрать list_id и собрать payload"
    },
    {
      "name": "Check idempotency",
      "type": "n8n-nodes-base.httpRequest",
      "purpose": "Найти dedupe_key"
    },
    {
      "name": "Create or update ClickUp task",
      "type": "n8n-nodes-base.httpRequest",
      "purpose": "Создать/обновить задачу"
    },
    {
      "name": "Notify owner",
      "type": "n8n-nodes-base.httpRequest",
      "purpose": "Отправить ссылку владельцу"
    },
    {
      "name": "Respond",
      "type": "n8n-nodes-base.respondToWebhook",
      "purpose": "Вернуть статус"
    }
  ],
  "connections": "Webhook task input → Route and normalize ClickUp task → Check idempotency → Create or update ClickUp task → Notify owner → Respond"
}

Пошаговая настройка связки ¶

1. Опишите event_type → list_id mapping в одном месте.
2. Создайте custom fields для external_id, source и customer_url.
3. Импортируйте workflow JSON и замените ClickUp API token/credentials.
4. Настройте Postgres/Data Store для dedupe_key.
5. Проверьте правила priority и due date на тестовых событиях.

Тесты перед production ¶

curl -X POST "https://YOUR-N8N-DOMAIN/webhook/integration-clickup-n8n-task-automation" \
  -H "Content-Type: application/json" \
  --data @integration-clickup-n8n-task-automation-payload.json

1. Один entity_id создаёт одну задачу.
2. Событие неизвестного типа попадает в Inbox list, а не теряется.
3. due_at в ISO-формате превращается в timestamp ClickUp.
4. Невалидный статус не отправляется в API.
5. Ошибка ClickUp API уходит в retry/DLQ.

Production-риски ¶

• Routing захардкожен в нескольких нодах. Смена List ломает часть событий.
• Нет dedupe_key. Повтор webhook создаёт повторную задачу.
• Custom fields не заполнены. Фильтры и отчёты ClickUp не работают.
• Приоритет маппится текстом. API ждёт конкретный формат.
• Нет fallback list. Неизвестные события теряются.

Полезные ссылки и смежные материалы ¶

• ClickUp Tasks API
• ClickUp Webhooks
• n8n ClickUp node
• Slack для owner-уведомлений
• Retry и DLQ для API-запросов

Критерии готовности ¶

1. event_type → list_id mapping зафиксирован и задокументирован.
2. Дедупликация работает до create task.
3. Priority, due date и custom fields проходят тесты.
4. У неизвестных событий есть fallback list и alert.
5. Rate limits ClickUp API покрыты retry/DLQ.