Guide

Webhooks vs polling

Two transports deliver updates to your bot. Polling is simpler; webhooks scale better. Start with polling, move to webhooks for production.

Polling

Call getUpdates in a loop with timeout: 50. The call hangs until an update arrives or 50 seconds pass. Confirm each batch by passing offset = last update_id + 1 on the next call; anything below the offset is never returned again.

import requests

BASE = "https://api.sprintelex.com"
H = {"Authorization": "Bearer <bot-token>"}
offset = 0
while True:
    r = requests.post(f"{BASE}/getUpdates",
                      headers=H,
                      json={"offset": offset, "timeout": 50}).json()
    for u in r["result"]["updates"]:
        handle(u)  # your code here
        offset = u["update_id"] + 1

Webhooks

Give us an HTTPS URL and we POST every update to it as JSON. Set one with setWebhook:

curl https://api.sprintelex.com/setWebhook \
  -H "Authorization: Bearer <bot-token>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/sprintex-webhook", "secret_token": "<random-string>"}'

Verifying deliveries

Every delivery carries two headers when you set a secret_token:

X-Sprintelex-Bot-Secret: <your secret_token, verbatim>
X-Sprintelex-Signature: sha256=<hex HMAC-SHA256(request body, secret_token)>

Check the signature on every request and reject anything that fails. Your endpoint must be HTTPS; plain HTTP is refused.

Retries

If your endpoint errors or times out, we retry with quadratic backoff (attempt² minutes between tries) for up to 24 hours, then the update is dead-lettered and dropped. A persistently failing endpoint gets disabled automatically, and the dashboard shows you the delivery log with status codes. Answer 200 fast and do slow work asynchronously.

Which to choose