Skip to main content

Webhooks

Mesachat uses webhooks to receive messages from external platforms.

Telegram Webhooks​

Endpoint​

POST /webhooks/telegram/:botId

How It Works​

  1. When a Telegram integration is created, Mesachat registers the webhook URL with Telegram's Bot API
  2. Telegram sends message updates to this URL
  3. Mesachat processes the message through the bot's configured agents

Security​

Webhooks can be secured with a secret token:

  • Set webhookSecretToken in integration settings
  • Telegram includes this token in the X-Telegram-Bot-Api-Secret-Token header
  • Mesachat validates the token before processing

Webhook Registration​

Mesachat handles webhook registration automatically:

  • On integration create — Registers webhook with Telegram
  • On integration update — Updates webhook if URL changed
  • On integration delete — Removes webhook from Telegram
  • Deduplication — Calls getWebhookInfo() before setWebhook() to avoid repeated registrations
  • Rate limiting — Exponential backoff for Telegram 429 responses

Clerk Webhooks​

Endpoint​

POST /api/webhooks/clerk

Purpose​

Syncs user data from Clerk to Mesachat's database:

EventAction
user.createdCreates Mesachat user
user.updatedUpdates Mesachat user
user.deletedRemoves Mesachat user
organization.*Syncs tenant data
organizationMembership.*Syncs memberships

Setup​

  1. In Clerk Dashboard → Webhooks → Add Endpoint
  2. URL: https://your-domain/api/webhooks/clerk
  3. Events: Select all user and organization events
  4. Copy signing secret to CLERK_WEBHOOK_SECRET env var

Custom Webhooks​

Coming Soon

Custom webhook endpoints for programmatic integrations are planned for a future release.