Skip to content
API Reference

Webhook Events Reference

3 min read · Updated Oct 14, 2026

Learn how to integrate PerfBee with your applications using webhooks. This guide covers every event type PerfBee sends, its payload, and how to verify that a webhook came from PerfBee.

Webhook Events Reference

PerfBee's webhooks notify you of crawl and credit events in your account. 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": "ISO 8601, UTC",
  "data": { ... }
}

PerfBee sends each event as an HTTP POST with a JSON body. The request also carries an X-PerfBee-Event header with the event name, and an X-PerfBee-Secret header when you have set a secret. The timestamp is in UTC without a time zone suffix, for example 2026-10-14T10:05:00.123456. Each event is sent once, with a 10-second timeout; a failed delivery is not retried.

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_completed: Fires when any crawl finishes successfully, whether or not it found broken links.
  • broken_links_found: Fires alongside scan_completed when broken links are detected.
  • scan_failed: Fires when a crawl fails before it finishes.
  • scheduled_scan_triggered: Fires when a scheduled crawl automatically starts.
  • credit_low: Fires once when 20% or less of your plan's monthly credits remain.
  • credit_exhausted: Fires once when your credits reach 0.

Event Details and Payloads

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

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 (a decimal number).
  • success_rate: Working links as a percentage of the links checked (0-100, two decimals).
  • result_url: The URL of the scan report in the dashboard.
  • scheduled_scan_uuid: The schedule that started the crawl, or null for a crawl started by hand.
{
  "event": "scan_completed",
  "event_description": "Scan completed successfully",
  "timestamp": "2026-10-14T10:05:00.123456",
  "data": {
    "scan_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "url": "https://example.com",
    "pages_checked": 50,
    "broken_count": 2,
    "working_count": 48,
    "duration_seconds": 300.4,
    "success_rate": 96.0,
    "result_url": "https://dashboard.perfbee.com/#/brokenLinks?scan=a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "scheduled_scan_uuid": null
  }
}

broken_links_found

This event is sent alongside scan_completed when broken links are found. The data payload is identical to scan_completed. PerfBee sends broken_links_found first, then 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: A description of the error.
  • timestamp: The time the failure was reported.
{
  "event": "scan_failed",
  "event_description": "Scan failed",
  "timestamp": "2026-10-14T10:05:00.123456",
  "data": {
    "scan_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "url": "https://example.com",
    "error": "Timeout during crawl",
    "timestamp": "2026-10-14T10:04:59.987654"
  }
}

scheduled_scan_triggered

Fires when a scheduled crawl starts automatically. The data object includes:

  • scan_uuid: Unique identifier for the crawl the schedule started.
  • url: The scheduled URL.
  • scheduled_scan_uuid: Unique identifier for the schedule.
  • run_count: How many times the schedule has run today.
{
  "event": "scheduled_scan_triggered",
  "event_description": "Scheduled scan triggered",
  "timestamp": "2026-10-14T03:00:00.123456",
  "data": {
    "scan_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "url": "https://example.com",
    "scheduled_scan_uuid": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "run_count": 1
  }
}

credit_low

Notifies you when your credit balance is low: 20% or less of your plan's monthly credits remain. PerfBee sends it once, on the action that takes the balance to 20% or less, and not again while it stays there. The data object includes:

  • credits_remaining: The number of credits remaining (can be a decimal number).
  • credits_limit: Your plan's monthly credits.
  • percentage: The percentage of credits remaining (one decimal).
{
  "event": "credit_low",
  "event_description": "Credits low (<20%)",
  "timestamp": "2026-10-14T10:00:00.123456",
  "data": {
    "credits_remaining": 1500.0,
    "credits_limit": 10000,
    "percentage": 15.0
  }
}

credit_exhausted

Alerts you when an action has used up your credits for the month. The data object includes:

  • credits_limit: Your plan's monthly credits.
  • credits_used: The credits used this month.
{
  "event": "credit_exhausted",
  "event_description": "Credits exhausted",
  "timestamp": "2026-10-14T10:00:00.123456",
  "data": {
    "credits_limit": 10000,
    "credits_used": 10000.0
  }
}

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, open Settings, select the Webhooks tab, enter a value in the Secret field and click Save Webhook.
  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.

PerfBee sends the secret itself, not a signature of the request body. Webhook URLs must use HTTPS, so the header travels encrypted; keep the secret private.

The Secret field stays empty when you return to the Webhooks tab. Saving the form with it empty keeps the stored secret; type a new one to replace it. Deleting the webhook removes it.

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