Webhook Notifications

Real-time monitoring via webhook notifications.

What are Webhooks?

Webhooks send HTTP POST requests to your server when events occur:

• Account authentication failures
• API rate limits reached
• General errors
• Warning conditions

Setup

1. Configure Webhook

const client = new XTwitterClient({
  webhook: {
    enabled: true,
    url: 'https://your-server.com/webhook',
    secret: 'your-secret-key',
    events: ['account_failure', 'api_rate_limit', 'error', 'warning']
  }
});

2. Create Endpoint

import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

app.post('/webhook', (req, res) => {
  // Verify signature
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const payload = JSON.stringify(req.body);
  
  const expectedSignature = crypto
    .createHmac('sha256', 'your-secret-key')
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook
  const { type, message, details } = req.body;
  console.log(`Webhook [${type}]: ${message}`);
  
  res.status(200).send('OK');
});

app.listen(3000);

Event Types

account_failure

Sent when a crawler account fails authentication:

{
  "type": "account_failure",
  "severity": "error",
  "message": "Crawler account authentication failed",
  "details": {
    "accountId": "account1",
    "failureReason": "cookies_expired"
  }
}

api_rate_limit

Sent when API rate limit is exceeded:

{
  "type": "api_rate_limit",
  "severity": "warning",
  "message": "X API rate limit exceeded",
  "details": {
    "endpoint": "/2/tweets/:id",
    "resetAt": "2025-12-17T18:00:00Z"
  }
}

Security

Webhooks include HMAC-SHA256 signatures:

• X-Webhook-Signature: HMAC signature
• X-Webhook-Timestamp: ISO timestamp
• X-Webhook-Id: Unique message ID

Always verify signatures before processing webhooks.

Features

• Retry Logic: Automatic retries with exponential backoff
• Rate Limiting: Prevent flooding (60/minute default)
• Deduplication: Avoid duplicate notifications (5 min window)
• Event Filtering: Subscribe to specific events only

Next Steps

• API Reference - Webhook configuration reference
• Error Handling - Error types