List Webhooks

Retrieve all webhooks associated with your API key, including their status, configuration, and delivery statistics.

Endpoint

HTTP Request

GET /webhooks
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Query Parameters

limit

Type: Integer
Description: Number of webhooks per page
Default: 20
Maximum: 100
Example: ?limit=50

status

Type: String
Description: Filter webhooks by status
Options: active, inactive, pending_verification, failed
Example: ?status=active

search

Type: String
Description: Search webhooks by URL or description
Example: ?search=programming

Response Format

Success Response (200 OK)

{
  "data": [
    {
      "id": "webhook_1234567890",
      "url": "https://your-domain.com/webhook",
      "events": ["tweet.created", "user.updated"],
      "filters": {
        "keywords": ["javascript", "programming"],
        "language": "en",
        "verified": true
      },
      "active": true,
      "description": "Track programming tweets from verified users",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "delivery_count": 1250,
      "failure_count": 3,
      "last_delivery_at": "2024-01-15T10:25:00Z",
      "last_failure_at": "2024-01-14T15:45:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3,
    "hasNext": true,
    "hasPrev": false
  }
}

Webhook Object Fields

Basic Information

id: Unique webhook identifier
url: Webhook endpoint URL
events: Array of subscribed event types
filters: Event filtering criteria
active: Whether webhook is currently active
description: Human-readable description

Status Information

status: Current webhook status
- active: Webhook is verified and receiving events
- inactive: Webhook is disabled
- pending_verification: Webhook awaiting verification
- failed: Webhook has delivery failures

Timestamps

created_at: When webhook was created
updated_at: When webhook was last updated
last_delivery_at: Last successful delivery timestamp
last_failure_at: Last failed delivery timestamp

Statistics

delivery_count: Total successful deliveries
failure_count: Total failed deliveries

Implementation Examples

JavaScript (Node.js)

const axios = require("axios");

async function listWebhooks(apiKey, options = {}) {
  try {
    const params = new URLSearchParams();

    if (options.page) params.append("page", options.page);
    if (options.limit) params.append("limit", options.limit);
    if (options.status) params.append("status", options.status);
    if (options.search) params.append("search", options.search);

    const response = await axios.get(`https://api.scrape.st/webhooks?${params}`, {
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
    });

    const webhooks = response.data;
    console.log(`Found ${webhooks.pagination.total} webhooks`);

    // Analyze webhook performance
    analyzeWebhookPerformance(webhooks.data);

    return webhooks;
  } catch (error) {
    console.error("Failed to list webhooks:", error.response?.data || error.message);
    throw error;
  }
}

function analyzeWebhookPerformance(webhooks) {
  console.log("\n=== Webhook Performance Analysis ===");

  webhooks.forEach((webhook) => {
    const successRate = (webhook.delivery_count / (webhook.delivery_count + webhook.failure_count)) * 100;
    const status = webhook.status === "active" ? "✅" : "❌";

    console.log(`${status} ${webhook.id}`);
    console.log(`  URL: ${webhook.url}`);
    console.log(`  Events: ${webhook.events.join(", ")}`);
    console.log(`  Success Rate: ${successRate.toFixed(2)}%`);
    console.log(`  Deliveries: ${webhook.delivery_count}, Failures: ${webhook.failure_count}`);

    if (webhook.last_failure_at) {
      const lastFailure = new Date(webhook.last_failure_at);
      console.log(`  Last Failure: ${lastFailure.toLocaleString()}`);
    }

    console.log("");
  });
}

// Usage
listWebhooks("your_api_key_here", {
  status: "active",
  limit: 50,
});

Python

import requests
from datetime import datetime

def list_webhooks(api_key, **options):
    params = {}
    if 'page' in options:
        params['page'] = options['page']
    if 'limit' in options:
        params['limit'] = options['limit']
    if 'status' in options:
        params['status'] = options['status']
    if 'search' in options:
        params['search'] = options['search']

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    try:
        response = requests.get("https://api.scrape.st/webhooks",
                             params=params, headers=headers)
        response.raise_for_status()
        webhooks = response.json()

        print(f"Found {webhooks['pagination']['total']} webhooks")

        # Analyze webhook performance
        analyze_webhook_performance(webhooks['data'])

        return webhooks
    except requests.exceptions.RequestException as error:
        print(f"Failed to list webhooks: {error}")
        if error.response:
            print(f"Error details: {error.response.text}")
        raise

def analyze_webhook_performance(webhooks):
    print("\n=== Webhook Performance Analysis ===")

    for webhook in webhooks:
        total = webhook['delivery_count'] + webhook['failure_count']
        success_rate = (webhook['delivery_count'] / total * 100) if total > 0 else 0
        status = "✅" if webhook['status'] == 'active' else "❌"

        print(f"{status} {webhook['id']}")
        print(f"  URL: {webhook['url']}")
        print(f"  Events: {', '.join(webhook['events'])}")
        print(f"  Success Rate: {success_rate:.2f}%")
        print(f"  Deliveries: {webhook['delivery_count']}, Failures: {webhook['failure_count']}")

        if webhook['last_failure_at']:
            last_failure = datetime.fromisoformat(webhook['last_failure_at'].replace('Z', '+00:00'))
            print(f"  Last Failure: {last_failure.strftime('%Y-%m-%d %H:%M:%S')}")

        print()

# Usage
list_webhooks("your_api_key_here", status="active", limit=50)

cURL

# List all webhooks
curl -X GET "https://api.scrape.st/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# List active webhooks with pagination
curl -X GET "https://api.scrape.st/webhooks?status=active&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Search webhooks
curl -X GET "https://api.scrape.st/webhooks?search=programming" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Advanced Filtering

Status Filtering

// Get webhooks by status
const activeWebhooks = await listWebhooks(apiKey, { status: "active" });
const failedWebhooks = await listWebhooks(apiKey, { status: "failed" });
const pendingWebhooks = await listWebhooks(apiKey, { status: "pending_verification" });

Search Functionality

// Search webhooks by URL or description
const programmingWebhooks = await listWebhooks(apiKey, {
  search: "programming",
});

const domainWebhooks = await listWebhooks(apiKey, {
  search: "your-domain.com",
});

Pagination Handling

async function getAllWebhooks(apiKey) {
  let allWebhooks = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await listWebhooks(apiKey, { page, limit: 100 });
    allWebhooks = allWebhooks.concat(response.data);

    hasMore = response.pagination.hasNext;
    page++;
  }

  return allWebhooks;
}

Performance Monitoring

Webhook Health Analysis

function analyzeWebhookHealth(webhooks) {
  const healthReport = {
    total: webhooks.length,
    active: 0,
    failed: 0,
    pending: 0,
    inactive: 0,
    averageSuccessRate: 0,
    problematicWebhooks: [],
  };

  let totalSuccessRate = 0;

  webhooks.forEach((webhook) => {
    // Count by status
    switch (webhook.status) {
      case "active":
        healthReport.active++;
        break;
      case "failed":
        healthReport.failed++;
        break;
      case "pending_verification":
        healthReport.pending++;
        break;
      case "inactive":
        healthReport.inactive++;
        break;
    }

    // Calculate success rate
    const total = webhook.delivery_count + webhook.failure_count;
    const successRate = total > 0 ? (webhook.delivery_count / total) * 100 : 0;
    totalSuccessRate += successRate;

    // Identify problematic webhooks
    if (successRate < 95 || webhook.failure_count > 10) {
      healthReport.problematicWebhooks.push({
        id: webhook.id,
        successRate,
        failures: webhook.failure_count,
        lastFailure: webhook.last_failure_at,
      });
    }
  });

  healthReport.averageSuccessRate = totalSuccessRate / webhooks.length;

  return healthReport;
}

Automated Monitoring

class WebhookMonitor {
  constructor(apiKey, checkInterval = 300000) {
    // 5 minutes
    this.apiKey = apiKey;
    this.checkInterval = checkInterval;
    this.alertThresholds = {
      minSuccessRate: 95,
      maxFailures: 10,
      maxInactiveTime: 3600000, // 1 hour
    };
  }

  start() {
    this.monitorInterval = setInterval(async () => {
      await this.performHealthCheck();
    }, this.checkInterval);

    console.log("Webhook monitoring started");
  }

  stop() {
    if (this.monitorInterval) {
      clearInterval(this.monitorInterval);
      console.log("Webhook monitoring stopped");
    }
  }

  async performHealthCheck() {
    try {
      const response = await listWebhooks(this.apiKey);
      const healthReport = analyzeWebhookHealth(response.data);

      this.evaluateHealth(healthReport);
    } catch (error) {
      console.error("Health check failed:", error);
    }
  }

  evaluateHealth(healthReport) {
    // Check for problematic webhooks
    if (healthReport.problematicWebhooks.length > 0) {
      this.sendAlert("problematic_webhooks", {
        count: healthReport.problematicWebhooks.length,
        webhooks: healthReport.problematicWebhooks,
      });
    }

    // Check overall success rate
    if (healthReport.averageSuccessRate < this.alertThresholds.minSuccessRate) {
      this.sendAlert("low_success_rate", {
        rate: healthReport.averageSuccessRate,
        threshold: this.alertThresholds.minSuccessRate,
      });
    }

    // Check failed webhooks
    if (healthReport.failed > 0) {
      this.sendAlert("failed_webhooks", {
        count: healthReport.failed,
      });
    }
  }

  sendAlert(type, data) {
    console.warn(`🚨 Webhook Alert: ${type}`, data);
    // Implement your alert notification logic here
  }
}

Error Handling

Common Error Responses

401 Unauthorized

{
  "error": "Invalid API key",
  "code": 401,
  "timestamp": "2024-01-15T10:30:00Z"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": 429,
  "retryAfter": 60
}

Error Handling Implementation

async function listWebhooksWithRetry(apiKey, options = {}, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await listWebhooks(apiKey, options);
    } catch (error) {
      if (error.response?.status === 429) {
        const retryAfter = error.response.data?.retryAfter || 60;
        console.log(`Rate limited, retrying in ${retryAfter} seconds...`);
        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (error.response?.status === 401) {
        throw new Error("Invalid API key");
      }

      if (attempt === maxRetries) {
        throw error;
      }

      const delay = Math.pow(2, attempt) * 1000;
      console.log(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }
}

Best Practices

For Monitoring

Regular Checks: Monitor webhook status and performance regularly
Alert Thresholds: Set appropriate alert thresholds for your use case
Performance Analysis: Track success rates and delivery patterns
Proactive Maintenance: Address issues before they become critical

For Performance

Pagination: Use pagination for large webhook lists
Caching: Cache webhook data to reduce API calls
Batch Operations: Process multiple webhooks together
Rate Limiting: Respect API rate limits and implement backoff

For Security

API Key Protection: Store API keys securely
Access Control: Implement appropriate access controls
Audit Logging: Log all webhook management operations
Regular Reviews: Regularly review webhook configurations

Next: Delete Webhook

​List Webhooks

​Endpoint

​HTTP Request

​Query Parameters

​page

​limit

​status

​search

​Response Format

​Success Response (200 OK)

​Webhook Object Fields

​Basic Information

​Status Information

​Timestamps

​Statistics

​Implementation Examples

​JavaScript (Node.js)

​Python

​cURL

​Advanced Filtering

​Status Filtering

​Search Functionality

​Pagination Handling

​Performance Monitoring

​Webhook Health Analysis

​Automated Monitoring

​Error Handling

​Common Error Responses

​401 Unauthorized

​429 Too Many Requests

​Error Handling Implementation

​Best Practices

​For Monitoring

​For Performance

​For Security

List Webhooks

Endpoint

HTTP Request

Query Parameters

page

limit

status

search

Response Format

Success Response (200 OK)

Webhook Object Fields

Basic Information

Status Information

Timestamps

Statistics

Implementation Examples

JavaScript (Node.js)

Python

cURL

Advanced Filtering

Status Filtering

Search Functionality

Pagination Handling

Performance Monitoring

Webhook Health Analysis

Automated Monitoring

Error Handling

Common Error Responses

401 Unauthorized

429 Too Many Requests

Error Handling Implementation

Best Practices

For Monitoring

For Performance

For Security