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 alongsidescan_completedwhen 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, ornullfor 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:
- Set a Secret: In your PerfBee Dashboard, open Settings, select the Webhooks tab, enter a value in the Secret field and click Save Webhook.
- Configure Your Server: Your server needs to be configured to receive and check the
X-PerfBee-Secretheader on incoming webhook requests. - Verify the Header: When a webhook is received, compare the value of the
X-PerfBee-Secretheader 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.