Вебхуки

Вебхук — это адрес на вашем сервере, который Posty5 вызывает, когда что-то происходит. Вместо того чтобы запрашивать у Posty5 новые посещения, ваша система получает уведомление за секунды в виде события JSON, которое можно проверить.

Создание эндпоинта

В панели управления Posty5 откройте настройки аккаунта и выберите вебхуки.
Добавьте эндпоинт, укажите его адрес HTTPS и выберите события, которые он получает.
Выберите все ссылки и QR-коды или только некоторые, учитывать ли посещения ботов и приходят ли события по одному или пакетами.
Сохраните, затем скопируйте секрет подписи. Он показывается только один раз.
Используйте отправку теста, чтобы убедиться, что сервер получает и проверяет событие webhook.test.

Адрес должен использовать HTTPS и быть доступен из интернета. Частные и локальные сетевые адреса отклоняются, а перенаправления не выполняются. Можно создать до 10 эндпоинтов.

События

Event
`short_link.visited`	Кто-то открыл одну из ваших коротких ссылок, в том числе через QR-изображение ссылки.
`short_link.visits_milestone`	Короткая ссылка достигла одного из заданных вами количеств посещений (до 10 значений).
`qr_code.scanned`	Кто-то отсканировал один из ваших динамических QR-кодов.
`qr_code.scans_milestone`	QR-код достиг одного из заданных вами количеств сканирований.
`webhook.test`	Отправляется только при использовании отправки теста.

Как выглядит событие

Каждое событие — это JSON POST с id, типом, версией API, временем создания и данными, то есть ссылкой или QR-кодом и посещением.

{
  "id": "evt_6700f1c2a9e4b51d2c3f0a11",
  "type": "short_link.visited",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-04T12:00:00.000Z",
  "data": {
    "target": {
      "type": "shortLink",
      "id": "66f0c2a9e4b51d2c3f0a1122",
      "code": "aB3xY9",
      "url": "https://pst5.com/_aB3xY9",
      "name": "Spring sale",
      "destinationUrl": "https://shop.example/sale",
      "tag": "spring",
      "refId": null
    },
    "visit": {
      "at": "2026-10-04T11:59:59.120Z",
      "channel": "qr",
      "country": "EG",
      "deviceType": "mobile",
      "os": "Android",
      "browser": "Chrome",
      "referrerHost": null,
      "language": "ar",
      "isBot": false,
      "outcome": "redirect"
    }
  }
}

События рубежей содержат data.milestone с метрикой, достигнутым значением и временем, без посещения.

При пакетной доставке один POST типа batch содержит до 500 событий в data.events.

Что никогда не отправляется

События никогда не содержат IP-адрес посетителя, полный user agent, полный адрес источника перехода, идентификатор посетителя или ID вашего аккаунта. Посещения ботов исключаются, если вы их не включите.

Проверка подписи

Posty5 подписывает каждую доставку секретом эндпоинта по спецификации Standard Webhooks в трёх заголовках. Отклоняйте любой запрос, подпись которого не совпадает или метка времени старше 5 минут.

webhook-id
webhook-timestamp
webhook-signature

В Node.js используйте пакет @posty5/webhooks.

import { verifyWebhookSignature } from "@posty5/webhooks";

// rawBody is the request body exactly as received, before JSON parsing.
const event = verifyWebhookSignature({
  payload: rawBody,
  headers: request.headers,
  secret: process.env.POSTY5_WEBHOOK_SECRET,
});

В .NET используйте пакет Posty5.Webhooks.

using Posty5.Webhooks;

var webhookEvent = WebhookSignature.Verify(rawBody, headers, secret);

В любом другом языке любая библиотека Standard Webhooks проверит события Posty5 с вашим секретом.

Повторы и сбои

Отвечайте любым статусом 2xx в течение 10 секунд. Всё остальное считается сбоем.
Неудачная доставка повторяется через 30 секунд, 2 минуты, 10 минут, 1 час, 6 часов и 24 часа, после чего прекращается.
Каждый повтор несёт тот же webhook-id, поэтому сервер может игнорировать уже обработанное событие.
Эндпоинт отключается после 20 неудачных доставок подряд в течение не менее 24 часов или сразу, если он отвечает 410 Gone. Вы получите уведомление и сможете снова включить его в панели управления.
Список доставок эндпоинта показывает каждую попытку со статусом и ответом вашего сервера и позволяет отправить доставку повторно.

Смена секрета

Если секрет мог утечь, смените его в меню эндпоинта. В течение 24 часов доставки несут две подписи, по одной на каждый секрет, чтобы можно было обновить сервер, не пропустив события.

Без кода, в n8n

Узел Posty5 Trigger сам создаёт и проверяет эндпоинт. n8n Posty5 Trigger