Вебхуки

Вебхук — HTTP-запрос, который платформа отправляет на URL вашей системы при событии с посылкой. Вебхуки настраивает администратор логистической компании через API управления вебхуками.

Постоматные события

`type`	`subtype`	Когда отправляется	Тело запроса
`PARCEL`	`DELIVERED_TO_POSTOMAT`	Посылка заложена в постомат	`{"postomatOrderId": "<ID заявки>", "status": 0}`
`PARCEL`	`TRANSFERRED_TO_CLIENT`	Получатель забрал посылку из постомата	`{"postomatOrderId": "<ID заявки>", "status": 1}`

Подробнее о событиях — Жизненный цикл посылки.

Формат запроса

http

POST {url}
Content-Type: application/json
x-api-key: YOUR_WEBHOOK_SECRET

{
  "postomatOrderId": "gfb0sfr5ahkhu9dns4bja2ly",
  "status": 0
}

Поле	Тип	Описание
`postomatOrderId`	string	ID заявки в сервисе постоматов, связанной с посылкой
`status`	number	`0` — посылка заложена в постомат, `1` — выдана получателю

Метод — POST, тело — JSON.
Заголовок x-api-key передаётся, только если при настройке вебхука указано поле apiKey.
Успешной считается доставка с ответом 2xx. Тело ответа не используется.

`payloadTemplate` для постоматных событий

Для подтипов DELIVERED_TO_POSTOMAT и TRANSFERRED_TO_CLIENT поле payloadTemplate обязательно. Это JSON-шаблон с плейсхолдерами и . Используйте шаблон по умолчанию:

json

{"postomatOrderId":"{{postomatOrderId}}","status":{{status}}}

Шаблон проверяется при сохранении: после подстановки он должен быть корректным JSON, другие плейсхолдеры не допускаются — иначе 406 WEBHOOK_PAYLOAD_INVALID.
подставляется числом, поэтому пишите его без кавычек.
Итоговое тело запроса всегда содержит ровно два поля — postomatOrderId и status (как в таблице выше). Шаблон не добавляет других полей.

Надёжность

Повторной отправки нет

Вебхук отправляется один раз. Если ваш сервер недоступен или ответил не 2xx, повторной отправки не будет. Периодически сверяйте статусы посылок запросами к API — см. Как отслеживать.

Проверяйте x-api-key. Задайте в apiKey случайный секрет и отклоняйте запросы с другим значением заголовка. Другой подписи у запроса нет.
Делайте обработчик идемпотентным: одно и то же событие может прийти от нескольких источников (например, от постомата и от курьера).
Отвечайте быстро и выполняйте обработку асинхронно.
Используйте HTTPS, например https://partner.example.com/webhooks/platform.
На тестовом окружении отправка вебхуков может быть отключена — уточните у менеджера InLog, если события не приходят.

import express from 'express'

const app = express()

app.post('/webhooks/platform', express.json(), (req, res) => {
  if (req.get('x-api-key') !== 'YOUR_WEBHOOK_SECRET') {
    return res.sendStatus(401)
  }
  res.sendStatus(200)

  const { postomatOrderId, status } = req.body
  queueParcelEvent({ postomatOrderId, event: status === 1 ? 'TRANSFERRED_TO_CLIENT' : 'DELIVERED_TO_POSTOMAT' })
})

queueParcelEvent — функция вашей системы.

API управления вебхуками

Все эндпоинты требуют JWT администратора логистической компании: Authorization: Bearer YOUR_JWT (см. Авторизация).

Метод	Путь	Назначение
`POST`	`/api/v1/logistic-company/webhook/create`	Создать вебхук
`PATCH`	`/api/v1/logistic-company/webhook/{id}`	Изменить вебхук
`GET`	`/api/v1/logistic-company/webhook/list`	Список вебхуков компании
`DELETE`	`/api/v1/logistic-company/webhook/{id}`	Удалить вебхук

Поля вебхука

Поле	Тип	Обязательное при создании	Описание
`type`	`PARCEL` \| `CARGO` \| `CAR` \| `NOTIFICATION` \| `ADVERTISEMENT`	да	Тип событий
`subtype`	`DELIVERED_TO_POSTOMAT` \| `TRANSFERRED_TO_CLIENT` \| `ITEM_CREATED` \| `ARRIVED_AT_DELIVERY` \| `null`	нет	Подтип. Сохраняется только для `type` = `PARCEL`, `CARGO`, `NOTIFICATION`; для остальных типов всегда `null`
`url`	string (URL)	да	Адрес вашего приёмника
`payloadTemplate`	string	для `DELIVERED_TO_POSTOMAT` и `TRANSFERRED_TO_CLIENT`	Шаблон тела, см. выше
`apiKey`	string \| null	нет	Значение заголовка `x-api-key` в запросах к вашему URL

У компании может быть только один вебхук на каждую пару type + subtype.

Другие типы и подтипы

API управления принимает и другие сочетания type/subtype. Их формат в этой версии документации не описан — если они нужны вашей интеграции, обратитесь к менеджеру InLog.

Создать вебхук

curlJavaScript (fetch)

bash

curl -X POST "https://api.inlog.ai/api/v1/logistic-company/webhook/create" \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PARCEL",
    "subtype": "DELIVERED_TO_POSTOMAT",
    "url": "https://partner.example.com/webhooks/platform",
    "payloadTemplate": "{\"postomatOrderId\":\"{{postomatOrderId}}\",\"status\":{{status}}}",
    "apiKey": "YOUR_WEBHOOK_SECRET"
  }'

const res = await fetch('https://api.inlog.ai/api/v1/logistic-company/webhook/create', {
  method: 'POST',
  headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'PARCEL',
    subtype: 'DELIVERED_TO_POSTOMAT',
    url: 'https://partner.example.com/webhooks/platform',
    payloadTemplate: '{"postomatOrderId":"{{postomatOrderId}}","status":{{status}}}',
    apiKey: 'YOUR_WEBHOOK_SECRET',
  }),
})
const webhook = await res.json()

Ответ 200:

json

{
  "id": 15,
  "type": "PARCEL",
  "subtype": "DELIVERED_TO_POSTOMAT",
  "url": "https://partner.example.com/webhooks/platform",
  "payloadTemplate": "{\"postomatOrderId\":\"{{postomatOrderId}}\",\"status\":{{status}}}",
  "apiKey": "YOUR_WEBHOOK_SECRET",
  "method": "POST",
  "companyId": 12,
  "createdAt": "2026-09-29T08:00:00.000Z",
  "updatedAt": "2026-09-29T08:00:00.000Z"
}

Создайте второй вебхук с subtype: "TRANSFERRED_TO_CLIENT", чтобы получать и событие выдачи.

Изменить вебхук

PATCH /api/v1/logistic-company/webhook/{id}

Все поля тела необязательны: type, subtype, url, payloadTemplate, apiKey. Непереданные type, subtype, url и payloadTemplate сохраняют прежние значения.

Список вебхуков

GET /api/v1/logistic-company/webhook/list?page=1&pageSize=20

Параметр	Тип	По умолчанию
`page`	integer, ≥ 1	`1`
`pageSize`	integer, ≥ 1	`1`

Размер страницы по умолчанию — 1

Передавайте pageSize явно, иначе вернётся один вебхук.

Ответ: { "total": number, "data": [WebHook] }.

Удалить вебхук

DELETE /api/v1/logistic-company/webhook/{id}

Ответ 200: { "message": "api key deleted" } — такой текст возвращается и при удалении вебхука.

Ошибки

HTTP	`message`	Когда
`400`	—	Ошибка валидации (`code: FST_ERR_VALIDATION`)
`401`	`TOKEN_NOT_VALID`, `UNAUTHORIZED`	Нет JWT или он недействителен
`403`	`FORBIDDEN`	Компания пользователя — не логистическая
`403`	`ONLY_FOR_ADMIN`	Пользователь — не администратор компании
`404`	`NOT_FOUND`	Вебхук не найден
`406`	`NOT_ACCEPTABLE`	Вебхук принадлежит другой компании
`406`	`WEBHOOK_TYPE_EXIST`	Вебхук с такими `type` и `subtype` уже есть
`406`	`WEBHOOK_PAYLOAD_INVALID`	Некорректный или отсутствующий `payloadTemplate`

Вебхуки ​

Постоматные события ​

Формат запроса ​

payloadTemplate для постоматных событий ​

Надёжность ​

API управления вебхуками ​

Поля вебхука ​

Создать вебхук ​

Изменить вебхук ​

Список вебхуков ​

Удалить вебхук ​

Ошибки ​