Webhooks — Overview & Setup
Welcome to the PerfBee API Reference! This article provides an overview of webhooks and how to set them up to receive notifications about events happening within your PerfBee account. Webhooks allow you to integrate PerfBee with your existing workflows, for example through n8n, Zapier or Make, to send notifications to Slack, trigger builds, or update your project management tools.
What are Webhooks?
Webhooks are automated messages sent from PerfBee to a specified URL (your endpoint) when a particular event occurs. Instead of checking PerfBee for updates, you receive the data as soon as the event happens. Common use cases include alerts about finished or failed crawls, broken links, and low credits.
Supported Events
Currently, PerfBee supports webhooks for the following events:
- Scan completed: Triggered when a Site Crawler crawl finishes.
- Broken links found: Triggered when a finished crawl found at least one broken link.
- Scan failed: Triggered when a crawl fails before it finishes.
- Scheduled scan triggered: Triggered when a scheduled crawl starts.
- Credits low: Triggered once when 20% or less of your monthly credits remain.
- Credits exhausted: Triggered once when your credits reach 0.
Other alerts, such as performance regressions, Critical CSS changes and RUM anomalies, are not sent as webhooks; they arrive as in-app notifications or emails.
Setting up Webhooks
To set up a webhook, you'll need a publicly accessible HTTPS URL (your endpoint) that can receive and process HTTP POST requests. This could be a script on your server, a function in your cloud provider, or any service capable of handling incoming data.
- Navigate to Settings: Log in to the PerfBee Dashboard and go to "Settings".
- Open the Webhooks Tab: Within Settings, select the "Webhooks" tab.
- Enter Your Endpoint URL: Provide the URL of your endpoint in the "Webhook URL" field. It must start with
https://and cannot point to a private or internal address. - Select Events to Subscribe To: Under "Events to Listen", choose the events you want to receive notifications for (e.g., Scan completed, Broken links found).
- Add a Secret (Optional): PerfBee sends it in the
X-PerfBee-Secretheader of every request. - Save Your Settings: Click the "Save Webhook" button to activate your webhook.
A workspace has one webhook URL. After you save, the "Send Test" button sends a test request to your endpoint. The test arrives as a scan_completed event with "test": true in its data, so it is only sent when Scan completed is selected.
Once set up, PerfBee will send a JSON payload to your endpoint whenever a selected event occurs. Every payload has the same wrapper: the event name, a description, a timestamp and a data object with the event's details. For a crawl, the data names the scan, its counts and a link to its report in the dashboard. PerfBee sends each event once and does not retry a failed delivery. See the Webhook Events Reference in the PerfBee Documentation for the payload of each event.
Example Payload (Broken links found):
{
"event": "broken_links_found",
"event_description": "Broken links found",
"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
}
}
The payload describes the crawl, not each broken link. Open result_url to see the broken links.
Security Considerations: Ensure your endpoint is secured and able to handle incoming requests. Set a secret in the Webhooks tab and check that the X-PerfBee-Secret header of each request matches it. PerfBee sends the secret as it is, not a signature of the request body.