Webhooks

You can configure webhooks so your platform can get notified when a test series is completed, if a budget changes status, or if there is a change in the performance opportunities for your website.

All calls are POSTs with a JSON body, and your platform must respond within 10 seconds with a 2xx status code (example "200 OK").

Enable the webhooks

Go to your website's settings page and click Integrations. Then, under "Webhooks", click "Enable".

We currently support two webhook events: "Test series completed" and "Multistep test completed".

Type in the URL of your webhook(s). If you just want to check how the webhooks works, you can use a webhook from https://webhook.site.

When you hit Done, PageVitals will fire a test call to the URL that you added and verify that it returns an HTTP status code within the 200-299 range.

Test series completed

When a test series completes or fails, PageVitals can fire an API call to your webhook URL that includes the test result. This is how the call looks like:

POST {your-webhook-url}
{
  "seriesId": "12345678",
  "created": "2023-06-28T12:34:45Z",
  "status": "completed",
  "initiative": "manual",
  "testCount": 10,
  "failedTests": 0,
  "results": [
    {
      "testId": "9i4sfoikw0wbm7id",
      "pageId": "12345678",
      "url": "https://pagevitals.com/",
      "device": "desktop",
      "created": "2023-06-28T12:35:15Z",
      "status": "completed",
      "lighthouse": {
        "version": "10.3.0",
        "location": "us-west2",
        "fcp": 234,
        "lcp": 1234,
        "tbt": 1850,
        "cls": 0.1,
        "ttfb": 345,
        "speed_index": 2636,
        "tti": 12504,
        "performance_score": 89,
        "accessibility_score": 100,
        "best_practices_score": 83,
        "seo_score": 92,
        "bytes_total": 2745,
        "cpu_total": 2371,
        "opportunities": 12,
        "budgets_exceeded": 3,
        "budgets_at_risk": 0,
        "validation_errors": 45
      },
      "crux": {
        "lcp": 1234,
        "fcp": 234,
        "fid": 3,
        "cls": 0.1,
        "inp": 340,
        "ttfb": 780,
        "passed": true
      }
    },
    ...
  ]
}

More information about the data sent:

Each item of the results array has these properties:

The lighthouse object has these properties:

The crux object is available if the page and device has an entry in the Chrome UX Report that is managed by Google. The object has these properties:

Multistep test completed

When a Multistep test completes or fails, PageVitals can fire an API call to your webhook URL that includes the test result. This is how the call looks like:

POST {your-webhook-url}
{
  "multistepTest": "jpe1el3j5y",
  "runId": "12345678",
  "website": "12345678",
  "created": "2023-06-28T12:34:45Z",
  "device": "mobile",
  "status": "completed",
  "location": "europe-west-1",
  "duration": 134400,
  "error": "",
  "fail_step": 0,
  "bytes_total": 450340,
  "cpu_total": 12340,
  "inp": 450,
  "tbt": 2340,
  "cls": 0.13,
  "lighthouse_version": "11.4",
  "chrome_version": "121"
}

More information about the data sent: