Webhooks — Overview & Setup

Welcome to the PerfBee API Reference! This article provides an overview of webhooks and how to set them up to receive real-time notifications about events happening within your PerfBee account. Webhooks allow you to integrate PerfBee with your existing workflows, such as sending notifications to Slack, triggering builds, or updating 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. This eliminates the need for you to constantly poll the PerfBee API for updates. Instead, PerfBee pushes the data to you as soon as the event happens. Common use cases include receiving alerts about broken links, performance regressions, and website downtime.

Supported Events

Currently, PerfBee supports webhooks for the following events:

Broken Link Detected: Triggered when the Site Crawler finds a broken link (4xx or 5xx error).
Performance Regression: Triggered when a Lighthouse audit reveals a performance decline.
Uptime Incident: Triggered when an endpoint monitored by Uptime Monitoring goes down.
Uptime Recovery: Triggered when an endpoint monitored by Uptime Monitoring recovers.

Setting up Webhooks

To set up a webhook, you'll need a publicly accessible 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 the "Settings" section.
Find Webhook Settings: Within the Settings, locate the "Webhooks" section.
Enter Your Endpoint URL: Provide the URL of your endpoint in the designated field.
Select Events to Subscribe To: Choose the events you want to receive notifications for (e.g., Broken Link Detected, Performance Regression).
Save Your Settings: Click the "Save" button to activate your webhooks.

Once set up, PerfBee will send a JSON payload to your endpoint whenever a selected event occurs. The payload will contain detailed information about the event, such as the URL of the broken link, the Lighthouse audit results, or the downtime details. Refer to the PerfBee Documentation for details on the specific payload structure for each event.

Example Payload (Broken Link):


{
  "event": "broken_link_detected",
  "timestamp": "2024-10-27T10:00:00Z",
  "url": "https://www.example.com/broken-page",
  "status_code": 404,
  "linked_from": "https://www.example.com/",
  "site_id": "your_site_id"
}

Security Considerations: Ensure your endpoint is secured and able to handle incoming requests. Consider implementing authentication and validation to prevent unauthorized access. The PerfBee API does not currently support any authentication methods for webhooks, so you will need to implement your own security measures.