Handling Webhook Requests¶

When someone hits a webhook URL, your command runs in a web context — with an HTTP request object instead of a Telegram update payload.

Same sandbox, different front door.

The request object¶

Your command gets a snapshot of the incoming HTTP call:

Example — guard by method¶

let method = request.method
let ip = request.ip
let ref = params.ref || request.query.ref

if (method !== "GET") {
  return res.status(405).json({ error: "GET only" })
}

Typical request.query for a user webhook:

{
  "command": "syncGameData",
  "options": "{\"level\":10}",
  "sig": "...",
  "user": "987654321",
  "ref": "profile",
  "lang": "en"
}

Parsed options are also available on the global options object. Custom URL params appear in params.

options and params¶

Two globals, two jobs:

let level = options.level        // from signed options JSON
let lang = params.lang           // from ?lang=en

Put secrets and tamper-sensitive data in options (signed). Put marketing tags and filters in params (visible in the URL).

What's available in webhooks¶

msg only exists when Telegram sends a message update — webhooks don't have one. Platform utilities (internal helpers tied to Telegram message context) are likewise unavailable here.

Telegram vs webhook data¶

Do not expect message or msg in webhook commands. If your logic branches on update type, check request instead.

Sending Telegram messages¶

User webhooks — chat.id is right there:

await Api.sendMessage({
  chat_id: chat.id,
  text: "Done!"
})

Global webhooks — you're on your own for chat_id:

await Api.sendMessage({
  chat_id: 123456789,
  text: "Cron job finished."
})

Command aliases¶

Webhooks resolve command names through the same alias system as Telegram commands. The command query value can be a primary name or any registered alias.

Errors before your command runs¶

The platform may reject a request before your Logic field executes:

Your command can return its own errors via res.

See also¶

• request
• params
• Limits & Security
• Sending Responses