# API Callback Notifications

https://api-docs.lumar.io/docs/notifications/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:

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

**Variables:**
```json
{
  "input": {
    "projectId": "TjAwNlByb2plY3QxMjM",
    "apiCallbackUrl": "https://www.example.com/webhook",
    "apiCallbackHeaders": [
      { "key": "Authorization", "value": "Bearer your-token" }
    ]
  }
}
```

**Response:**
```json
{
  "data": {
    "updateProject": {
      "project": {
        "id": "TjAwNlByb2plY3QxMjM",
        "apiCallbackUrl": "https://www.example.com/webhook",
        "apiCallbackHeaders": [
          { "key": "Authorization", "value": "Bearer your-token" }
        ]
      }
    }
  }
}
```

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](/docs/notifications/webhook-notifications.md#callback-failed) 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.

```typescript
{
  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.

```typescript
{
  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"
}
```