StarsPaymee
Открыть бота
Бизнес

Интеграция webhook для Telegram Stars API

Получайте статус заказа и оплаты в реальном времени через webhook: проверка подписи, идемпотентность, retry и лучшие практики. Автоинтеграция с API StarsPaymee — 18 вопросов‑ответов.

Краткий ответ

Webhook — HTTP‑запрос, который API StarsPaymee автоматически отправляет на ваш сервер при смене статуса заказа или оплаты. Благодаря ему вы не опрашиваете статус постоянно (polling), а сразу реагируете, как только приходит событие «delivered» или «failed». Webhook — сердце автоматической интеграции.

Что такое webhook и зачем он нужен?

При polling вы каждые несколько секунд спрашиваете «заказ готов?» — это тратит ресурсы и медленно. При webhook API сам уведомляет вас, как только произошло событие. Это быстрее, дешевле и ближе к реальному времени.

Что приходит в webhook?
  • Тип события — order.delivered, order.failed, payment.success.
  • ID заказа и статус.
  • Отметка времени (timestamp).
  • Подпись (signature) — для проверки подлинности.

Как подключить webhook?

  1. 1. Укажите URLВ панели StarsPaymee укажите адрес webhook (HTTPS).
  2. 2. Проверяйте подписьВ каждом запросе проверяйте signature секретным ключом.
  3. 3. ИдемпотентностьСохраняйте ID события и не обрабатывайте повтор.
  4. 4. Быстрый ответВозвращайте 200 OK; тяжёлую работу ставьте в очередь.

Нужна интеграция webhook? Свяжитесь с Business.

@StarsPaymee_bot

Лучшие практики

Для надёжного webhook
  • Используйте только HTTPS.
  • Всегда проверяйте подпись.
  • Предотвращайте повтор ключом идемпотентности.
  • Учитывайте политику повторов (retry).
  • Логируйте и мониторьте события.

Связанное: Stars API, callback Click и подключение платёжного API к боту.

Источники

Часто задаваемые вопросы

Что такое webhook?
Автоматический HTTP‑запрос, который API шлёт на ваш сервер при смене статуса заказа/оплаты.
Разница webhook и polling?
При polling вы опрашиваете; при webhook API сам уведомляет — быстрее и дешевле.
Как подключить webhook?
Укажите HTTPS URL в панели; проверяйте подпись и возвращайте 200 OK.
Какие события приходят?
order.delivered, order.failed, payment.success и другие.
Зачем подпись (signature)?
Для проверки подлинности запроса — поддельный webhook отклоняется.
Что такое идемпотентность?
Механизм не обрабатывать повтор события (по ID).
Как быстро отвечать?
Быстро — 200 OK; тяжёлую работу в очередь.
Будет ли retry?
Да. При недоставке API может повторить; с идемпотентностью безопасно.
HTTPS обязателен?
Да. Для безопасности только HTTPS.
Можно ли тестировать?
Да. Поток webhook можно проверить в Sandbox.
Нужны ли логи?
Да. Логируйте и мониторьте события.
Что если webhook не пришёл?
Как резерв статус проверяется через GET /orders/{id}.
Можно ли подписаться на несколько событий?
Да. Подписываетесь на нужные типы событий.
Связан ли с callback Click?
Похожий принцип; callback Click — про оплату, webhook — про доставку.
Что ещё для безопасности?
Ограничение IP, секретный ключ и проверка отметки времени.
В формате JSON?
Да. Тело webhook в виде JSON.
Дают ли документацию?
Да. С форматом события и проверкой подписи.
Как начать?
Оставьте заявку на странице StarsPaymee Business.

Подключите webhook

Через StarsPaymee Business постройте интеграцию в реальном времени с webhook.

Открыть бот