Skip to main content

​
Webhook Delivery

Configure HTTPS webhook URLs on your stream monitors or filter rules to receive HTTP POST callbacks for each detected tweet. All webhooks are signed with HMAC-SHA256.

​
Setup

Set webhook_url when creating a monitor or filter rule: 
curl -X POST "https://scrapebadger.com/v1/twitter/stream/monitors" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Monitor",
    "usernames": ["elonmusk"],
    "webhook_url": "https://example.com/webhooks/tweets",
    "webhook_secret": "my-secret-key"
  }'
If you omit webhook_secret, one is auto-generated and returned in the response.

​
Webhook payload

POST https://example.com/webhooks/tweets
Content-Type: application/json
X-Signature-256: sha256=a1b2c3d4...
X-Webhook-Id: wh_abc123
X-Delivery-Id: del_xyz789

{
  "event": "tweet.detected",
  "monitor_id": "abc-123",
  "monitor_name": "My Monitor",
  "tweet_id": "1234567890",
  "author_username": "elonmusk",
  "tweet_text": "Just announced...",
  "tweet_url": "https://x.com/elonmusk/status/1234567890",
  "tweet_published_at": "2026-03-13T12:00:00Z",
  "detected_at": "2026-03-13T12:00:00.150Z",
  "latency_ms": 150,
  "tweet_data": {
    "id": "1234567890",
    "text": "Just announced...",
    "user": { ... },
    "media": [ ... ]
  }
}

​
Signature verification

Every webhook includes an X-Signature-256 header. Verify it to ensure the request is from ScrapeBadger:

​
Python

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

​
Node.js

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

​
Retry behavior

  • ScrapeBadger expects a 2xx response within 10 seconds
  • Failed deliveries are retried up to 3 times with exponential backoff
  • Delivery status is visible in the delivery logs endpoint

​
Testing webhooks

Use the test endpoint to send a sample payload to your webhook URL: 
curl -X POST "https://scrapebadger.com/v1/twitter/stream/webhooks/test" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monitor_id": "your-monitor-id"}'

​
Managing webhooks

You can also manage webhooks separately from monitors using the dedicated webhook endpoints:

Create Webhook

POST /v1/twitter/stream/webhooks

List Webhooks

GET /v1/twitter/stream/webhooks

Delete Webhook

DELETE /v1/twitter/stream/webhooks/

Test Webhook

POST /v1/twitter/stream/webhooks/test