StarsPaymee
Open the bot
Business

Webhook integration for the Telegram Stars API

Get order and payment status in real time via webhook: signature verification, idempotency, retry and best practices. Automatic integration with the StarsPaymee API — 18 Q&A.

Short answer

A webhook is an HTTP request that the StarsPaymee API sends to your server automatically when an order or payment status changes. Thanks to it you don't poll the status constantly — instead you react as soon as a «delivered» or «failed» event arrives. The webhook is the heart of automatic integration.

What is a webhook and why is it needed?

With polling you ask «is the order ready?» every few seconds — which wastes resources and is slow. With a webhook the API notifies you as soon as an event happens. It's faster, cheaper and closer to real time.

What arrives in a webhook?
  • Event type — order.delivered, order.failed, payment.success.
  • Order ID and status.
  • A timestamp.
  • A signature — to verify authenticity.

How do I connect a webhook?

  1. 1. Provide a URLIn the StarsPaymee panel provide your webhook URL (HTTPS).
  2. 2. Verify the signatureVerify the signature with a secret key on every incoming request.
  3. 3. IdempotencyStore the event ID and don't reprocess a repeat.
  4. 4. Respond quicklyReturn 200 OK; put heavy work in a queue.

Need webhook integration? Contact Business.

@StarsPaymee_bot

Best practices

For a reliable webhook
  • Use HTTPS only.
  • Always verify the signature.
  • Prevent repeats with an idempotency key.
  • Account for a retry policy.
  • Log and monitor events.

Related: Stars API, Click callback and connecting a payment API to a bot.

Sources

Frequently asked questions

What is a webhook?
An automatic HTTP request the API sends to your server when an order/payment status changes.
Difference between webhook and polling?
With polling you ask; with a webhook the API notifies you — faster and cheaper.
How do I connect a webhook?
Provide an HTTPS URL in the panel; verify the signature and return 200 OK.
Which events arrive?
order.delivered, order.failed, payment.success and others.
Why a signature?
To verify the request's authenticity — a fake webhook is rejected.
What is idempotency?
A mechanism to not reprocess a repeated event (by ID).
How fast should I respond?
Fast — 200 OK; put heavy work in a queue.
Will there be retries?
Yes. On non‑delivery the API may retry; safe with idempotency.
Is HTTPS required?
Yes. For security, HTTPS only.
Can I test it?
Yes. The webhook flow can be tested in the Sandbox.
Are logs needed?
Yes. Log and monitor events.
What if the webhook didn't arrive?
As a fallback the status is checked via GET /orders/{id}.
Can I subscribe to several events?
Yes. You subscribe to the event types you need.
Is it related to the Click callback?
A similar principle; the Click callback is about payment, the webhook about delivery.
What else for security?
IP restriction, a secret key and timestamp verification.
Is it in JSON?
Yes. The webhook body is in JSON.
Is documentation provided?
Yes. With the event format and signature verification.
How do I start?
Submit a request on the StarsPaymee Business page.

Connect the webhook

Through StarsPaymee Business, build a real‑time integration with webhooks.

Open the bot