Skip to main content

Webhooks

Webhooks allow you to receive real-time notifications about events in your Telegram channels. Instead of constantly polling the API for updates, webhooks push data to your server when events occur.

Overview​

Telegram Analytics webhooks send HTTP POST requests to a URL you specify whenever certain events occur in your connected channels. This enables you to:

  • Receive real-time notifications about subscriber milestones
  • Get instant alerts about viral posts
  • Monitor engagement drops as they happen
  • Integrate Telegram Analytics data with your own systems

Setting Up Webhooks​

Prerequisites​

Before setting up webhooks, you'll need:

  • A publicly accessible HTTPS endpoint that can receive POST requests
  • The ability to process JSON payloads
  • A Telegram Analytics account with API access

Registration Process​

  1. Log in to your Telegram Analytics dashboard
  2. Navigate to Settings > Webhooks
  3. Click "Add Webhook"
  4. Enter your webhook URL (must use HTTPS)
  5. Select the events you want to subscribe to
  6. Choose which channels to monitor
  7. Click "Create Webhook"

Alternatively, you can register webhooks programmatically using the API.

Event Types​

Telegram Analytics supports the following webhook event types:

Subscriber Events​

  • subscriber_milestone: Triggered when your channel reaches subscriber milestones
  • subscriber_spike: Triggered when there's an unusual increase in subscribers
  • subscriber_drop: Triggered when there's an unusual decrease in subscribers

Content Events​

  • viral_post: Triggered when a post performs significantly better than average
  • high_engagement: Triggered when a post receives exceptional engagement
  • low_engagement: Triggered when a post performs significantly worse than average

Performance Events​

  • engagement_drop: Triggered when overall engagement decreases significantly
  • view_rate_change: Triggered when the average view rate changes significantly

Webhook Payload​

Webhook requests are sent as HTTP POST requests with a JSON payload. Here's an example payload for a subscriber_milestone event:

{
  "event_type": "subscriber_milestone",
  "timestamp": "2023-06-15T10:30:00Z",
  "webhook_id": "webhook789",
  "channel": {
    "id": "channel123",
    "title": "My Channel",
    "username": "mychannel"
  },
  "data": {
    "milestone": 10000,
    "previous_milestone": 5000,
    "time_to_milestone": "45d 12h",
    "growth_rate": 0.15
  }
}

And here's an example for a viral_post event:

{
  "event_type": "viral_post",
  "timestamp": "2023-06-16T14:25:00Z",
  "webhook_id": "webhook789",
  "channel": {
    "id": "channel123",
    "title": "My Channel",
    "username": "mychannel"
  },
  "data": {
    "post_id": "post456",
    "post_date": "2023-06-16T12:00:00Z",
    "views": 15000,
    "expected_views": 8000,
    "performance_increase": 0.875,
    "shares": 350,
    "reactions": 620,
    "content_preview": "Breaking news: ..."
  }
}

Security Considerations​

Webhook Signatures​

To verify that webhook requests are coming from Telegram Analytics, each request includes a signature in the X-Telegram-Analytics-Signature header. The signature is a HMAC-SHA256 hash of the request body using your webhook secret as the key.

To verify the signature:

  1. Retrieve the signature from the X-Telegram-Analytics-Signature header
  2. Compute the HMAC-SHA256 hash of the request body using your webhook secret
  3. Compare the computed hash with the signature from the header

Example Verification (Node.js)​

const crypto = require('crypto');

function verifyWebhookSignature(body, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(computedSignature),
    Buffer.from(signature)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-telegram-analytics-signature'];
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  // ...
  
  res.status(200).send('OK');
});

Best Practices​

Webhook Reliability​

To ensure reliable webhook processing:

  1. Respond Quickly: Return a 200 OK response as soon as possible, ideally within 3 seconds
  2. Process Asynchronously: Handle the actual processing of webhook data after responding
  3. Implement Retries: Be prepared to handle the same event multiple times
  4. Store Raw Events: Save the raw webhook payload before processing

Error Handling​

If your endpoint fails to respond with a 200 OK status, Telegram Analytics will retry the webhook with an exponential backoff:

  • First retry: 5 seconds after failure
  • Second retry: 10 seconds after first retry
  • Third retry: 20 seconds after second retry
  • And so on, up to a maximum of 5 retries

Managing Webhooks​

Listing Webhooks​

To view all registered webhooks:

  1. Navigate to Settings > Webhooks in the dashboard
  2. All active webhooks will be displayed with their event types and channels

Testing Webhooks​

To test a webhook:

  1. Navigate to Settings > Webhooks
  2. Select the webhook you want to test
  3. Click "Send Test Event"
  4. Choose an event type
  5. Click "Send"

This will send a test event to your webhook endpoint.

Disabling Webhooks​

To temporarily disable a webhook:

  1. Navigate to Settings > Webhooks
  2. Find the webhook you want to disable
  3. Toggle the "Active" switch to off

Deleting Webhooks​

To permanently delete a webhook:

  1. Navigate to Settings > Webhooks
  2. Find the webhook you want to delete
  3. Click the "Delete" button
  4. Confirm the deletion

Next Steps​

For more information on integrating with Telegram Analytics: