Webhook Events Reference

Webhook Events Reference

PerfBee offers a robust webhook system to notify you of important events related to your web performance monitoring. This allows you to integrate PerfBee data directly into your workflows and applications. All webhook payloads share a common wrapper format:

{
  "event": "event_name",
  "event_description": "Human readable",
  "timestamp": "ISO8601",
  "data": { ... }
}

Each event_name corresponds to a specific action or state change within PerfBee. Below, we detail each event type, its trigger conditions, and the data it provides.

Event Types

• scan_started: Fires when a crawl begins.
• scan_completed: Fires when any crawl finishes successfully.
• broken_links_found: Fires alongside scan_completed when broken links are detected.
• scan_failed: Fires when a crawl encounters an error.
• scheduled_scan_triggered: Fires when a scheduled crawl automatically starts.
• credit_low: Fires when your remaining credits fall below 20% of your plan limit.
• credit_exhausted: Fires when your credits reach 0.

Event Details and Payloads

Here's a breakdown of each event and its associated data:

scan_started

This event signals the beginning of a crawl. The data object includes:

• scan_uuid: Unique identifier for the scan.
• url: The starting URL for the crawl.
• max_pages: The maximum number of pages to be crawled.
• progress_url: A URL to monitor the crawl's progress (not currently implemented).

{
  "event": "scan_started",
  "event_description": "Crawl started",
  "timestamp": "2024-07-27T10:00:00Z",
  "data": {
    "scan_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "url": "https://example.com",
    "max_pages": 100,
    "progress_url": null
  }
}

scan_completed

Indicates a successful crawl completion. The data object includes:

• scan_uuid: Unique identifier for the scan.
• url: The starting URL for the crawl.
• pages_checked: The number of pages checked during the crawl.
• broken_count: The number of broken links found.
• working_count: The number of working links found.
• duration_seconds: The crawl duration in seconds.
• success_rate: The crawl success rate (0-100).
• result_url: The URL to view the crawl results.

{
  "event": "scan_completed",
  "event_description": "Crawl completed successfully",
  "timestamp": "2024-07-27T10:05:00Z",
  "data": {
    "scan_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "url": "https://example.com",
    "pages_checked": 50,
    "broken_count": 2,
    "working_count": 48,
    "duration_seconds": 300,
    "success_rate": 96,
    "result_url": "https://dashboard.perfbee.com/broken-links/a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
}

broken_links_found

This event is sent *alongside* scan_completed when broken links are found. The data payload is identical to scan_completed.

scan_failed

This event signals a crawl failure. The data object includes:

• scan_uuid: Unique identifier for the scan.
• url: The starting URL for the crawl.
• error_message: A description of the error.
• timestamp: The time the error occurred.

{
  "event": "scan_failed",
  "event_description": "Crawl failed",
  "timestamp": "2024-07-27T10:05:00Z",
  "data": {
    "scan_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "url": "https://example.com",
    "error_message": "Timeout during crawl",
    "timestamp": "2024-07-27T10:04:59Z"
  }
}

scheduled_scan_triggered

Fires when a scheduled crawl starts automatically. The data payload is identical to the scan_started event.

credit_low

Notifies you when your credit balance is low (below 20% of your plan limit). The data object includes:

• credits_remaining: The number of credits remaining.
• credits_limit: The total number of credits for your plan.
• percentage: The percentage of credits remaining.

{
  "event": "credit_low",
  "event_description": "Credits are low",
  "timestamp": "2024-07-27T10:00:00Z",
  "data": {
    "credits_remaining": 1000,
    "credits_limit": 15000,
    "percentage": 6.67
  }
}

credit_exhausted

Alerts you when you've used all your credits. The data object includes:

• message: A descriptive message.
• upgrade_url: A URL to upgrade your plan.

{
  "event": "credit_exhausted",
  "event_description": "Credits exhausted",
  "timestamp": "2024-07-27T10:00:00Z",
  "data": {
    "message": "Your credit balance has reached 0.",
    "upgrade_url": "https://dashboard.perfbee.com/billing"
  }
}

Verifying Webhook Authenticity

To ensure the integrity of incoming webhooks, PerfBee allows you to verify their authenticity using the X-PerfBee-Secret header. Here's how to do it:

1. Set a Secret: In your PerfBee Dashboard, navigate to the Settings section. There, you can define a unique secret for your account.
2. Configure Your Server: Your server needs to be configured to receive and check the X-PerfBee-Secret header on incoming webhook requests.
3. Verify the Header: When a webhook is received, compare the value of the X-PerfBee-Secret header to the secret you configured in your PerfBee settings. If the values match, you can be confident that the webhook originated from PerfBee.

By implementing this verification process, you can protect your application from malicious actors and ensure that you're only processing legitimate PerfBee webhook events.