API Callback Notifications

API callback notifications are HTTP POST requests sent to the URL configured in your project or account settings (apiCallbackUrl). They notify your application when specific events complete.

Configuration

Set the callback URL on a project using the updateProject mutation:

Operation: mutation ConfigureApiCallbackUrl($input: UpdateProjectInput!) { updateProject(input: $input) { project { id apiCallbackUrl apiCallbackHeaders { key value } } } }Variables: { "input": { "projectId": "TjAwNlByb2plY3QxMjM", "apiCallbackUrl": "https://www.example.com/webhook", "apiCallbackHeaders": [ { "key": "Authorization", "value": "Bearer your-token" } ] } }Response Example: { "data": { "updateProject": { "project": { "id": "TjAwNlByb2plY3QxMjM", "apiCallbackUrl": "https://www.example.com/webhook", "apiCallbackHeaders": [ { "key": "Authorization", "value": "Bearer your-token" } ] } } } }

ConfigureApiCallbackUrlTry in Explorer

GraphQL

mutation ConfigureApiCallbackUrl($input: UpdateProjectInput!) {
  updateProject(input: $input) {
    project {
      id
      apiCallbackUrl
      apiCallbackHeaders {
        key
        value
      }
    }
  }
}

The callback URL can also be set at the account level. If both are set, the project-level URL takes priority.

Delivery details

• HTTP method: POST
• Content-Type: application/x-www-form-urlencoded
• Timeout: 30 seconds
• Success status codes: 200, 201, 202, 203, 204

If the callback request fails, a callback-failed webhook notification is sent to the SSO client webhook URL (if configured).

Events

Crawl Finished

Sent when a crawl completes successfully. Only fires for standard crawls, not test suite builds.

{
  message: "crawl_status",
  resource: "crawl",
  crawl_id: 124234,
  project_id: 1123123,
  account_id: 123123,
  /**
   * Crawl created by User's ID. Empty string if not available.
   */
  user_id: 123123,
  /**
   * SSO client account ID. Empty string if not available.
   */
  partner_account_id: "123123",
  /**
   * SSO user ID. Empty string if not available.
   */
  partner_user_id: "3333312",
  /**
   * Crawl status. Should be "finished".
   */
  status: "finished",
  /**
   * Relative legacy API URL for the crawl.
   */
  href: "/accounts/123123/projects/1123123/crawls/124234"
}

Report Download Generated

Sent when a report download finishes generating and is ready to be retrieved.

{
  message: "report_download_available",
  resource: "report_download",
  /**
   * Report download ID.
   */
  report_download_id: 567890,
  /**
   * Report identifier in the format "crawlId:reportTemplateCode:reportTypeCode" or
   * "crawlId:reportTemplateCode:reportTypeCode:segmentId" if segmented.
   * @example "124234:all_pages:basic"
   */
  report_id: "124234:all_pages:basic",
  crawl_id: 124234,
  project_id: 1123123,
  account_id: 123123,
  /**
   * Crawl created by User's ID. Empty string if not available.
   */
  user_id: 123123,
  /**
   * SSO client account ID. Empty string if not available.
   */
  partner_account_id: "123123",
  /**
   * SSO user ID. Empty string if not available.
   */
  partner_user_id: "3333312",
  status: "generated",
  /**
   * S3 signed URL to download the generated report.
   */
  file_url: "https://...",
  /**
   * Relative legacy API URL for the report download.
   * @example "/accounts/1/projects/2/crawls/3/reports/4:all_pages:basic/downloads/5"
   */
  href: "/accounts/123123/projects/1123123/crawls/124234/reports/124234:all_pages:basic/downloads/567890"
}