Подписка и события

Вебхук — это POST-запрос от DoneBy на ваш адрес, когда в пространстве что-то произошло: задачу создали, перенесли, выполнили. Вместо того чтобы опрашивать API каждую минуту, ваш сервер узнаёт об изменении сразу.

Подключение в настройках

1. Откройте Настройки → Вебхуки и нажмите «Добавить адрес».
2. Укажите URL. Принимаются только адреса https:// с действительным сертификатом; адреса внутренних сетей (localhost, 10.x.x.x, 192.168.x.x) не принимаются.
3. Отметьте события. Можно выбрать все, но лучше только нужные — меньше лишних запросов к вашему серверу.
4. Сохраните и скопируйте секрет адреса — им подписывается каждая доставка. Секрет показывается один раз, потом его можно только перевыпустить.

В карточке адреса видны последние доставки: тип события, код ответа вашего сервера, время и номер попытки. Это первое место, куда стоит смотреть, если события «не приходят».

Подключение через API

То же самое делается запросом POST /webhooks с токеном, у которого есть скоуп webhooks:write. В ответе — секрет адреса, и это единственный раз, когда API его показывает.

curl -X POST https://doneby.app/api/v1/webhooks \
  -H "Authorization: Bearer $DONEBY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a7e2f40-1b6c-4d3e-8f25-c0d4b7a91e63" \
  -d '{
    "url": "https://example.com/hooks/doneby",
    "events": ["task.created", "task.completed", "task.due_soon"],
    "description": "Задачи в CRM"
  }'

{
  "id": "whk_3Tq8Yb",
  "url": "https://example.com/hooks/doneby",
  "events": ["task.created", "task.completed", "task.due_soon"],
  "description": "Задачи в CRM",
  "secret": "c2f1a9e04b7d6385f0e1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3",
  "enabled": true,
  "created_at": "2026-09-24T08:40:00Z"
}

GET /webhooks возвращает все адреса пространства — без секретов. DELETE /webhooks/{id} отключает и удаляет адрес. Список событий удобнее менять в настройках.

События

Подписаться можно на любое сочетание событий. Объекты в data — в том же формате, что в REST API.

Формат доставки

Каждое событие — отдельный POST с JSON-телом и заголовком подписи. Конверт одинаковый для всех типов:

POST /hooks/doneby HTTP/1.1
Host: example.com
Content-Type: application/json
X-DoneBy-Signature: t=1758707412,v1=3b9f0c7e1d4a26f58c0e9b7a1f2d3c4b5a69788f7e6d5c4b3a2918070f6e5d4c

{
  "id": "evt_6Rk2Pw",
  "type": "task.completed",
  "created_at": "2026-09-24T09:50:12Z",
  "workspace_id": "wsp_9Dn4Tz",
  "data": {
    "task": {
      "id": "tsk_4Gh8Np",
      "title": "Созвон по правкам карточек товара",
      "list_id": "lst_Ka7Tp3",
      "due_date": "2026-09-24",
      "due_time": "14:30",
      "timezone": "Europe/Moscow",
      "priority": 1,
      "assignee_ids": ["usr_Ol3gD7", "usr_Me0001"],
      "completed": true,
      "completed_at": "2026-09-24T09:50:12Z",
      "updated_at": "2026-09-24T09:50:12Z",
      "url": "https://doneby.app/app/list/lst_Ka7Tp3?task=tsk_4Gh8Np"
    },
    "completed_by": "usr_Ol3gD7"
  }
}

У task.updated в data есть ещё changed — список изменённых полей — и previous с их прежними значениями. Так легко отличить перенос срока от смены исполнителя, не храня у себя копию задачи.

{
  "id": "evt_6Rk2Px",
  "type": "task.updated",
  "created_at": "2026-09-24T10:02:47Z",
  "workspace_id": "wsp_9Dn4Tz",
  "data": {
    "task": {
      "id": "tsk_8Kd2Lq",
      "title": "Подготовить отчёт за сентябрь",
      "due_date": "2026-10-01",
      "due_time": null,
      "updated_at": "2026-09-24T10:02:47Z"
    },
    "changed": ["due_date", "due_time"],
    "previous": { "due_date": "2026-09-30", "due_time": "15:00" }
  }
}

Как отвечать

• Ответьте любым кодом 2xx в течение 10 секунд — доставка засчитана. Тело ответа DoneBy не читает.
• Всё остальное считается неудачей: 3xx (редиректы не выполняются), 4xx, 5xx, таймаут, ошибка TLS или соединения. Событие уйдёт на повтор по расписанию.
• Сначала ответьте, потом обрабатывайте. Положите событие в очередь, верните 200 и разбирайте его в фоне. Долгая обработка внутри запроса — самая частая причина повторов и дублей.
• Прежде чем что-то делать с событием, проверьте подпись.

Ограничения по тарифам

Один адрес может получать сколько угодно типов событий. Ответ — 10 секунд, повторы — до 6 попыток на событие. Подробности о подписи, повторах и отключении адреса — в разделе Подпись и повторы.