> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bugster.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Integration

> Integrate Bugster with any deployment platform using our webhook API

Create a custom integration with Bugster to run tests on your preferred deployment infrastructure. Perfect for teams using platforms not covered by our built-in integrations.

## Overview

The custom integration uses Bugster's webhook API to trigger test runs when your deployments are ready. This approach gives you full control over when and how Bugster tests are executed in your deployment pipeline.

<Tip>
  The custom integration is the same API that powers our GitHub Actions integration behind the scenes.
</Tip>

## API Endpoint

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.bugster.app/webhooks/integrations/custom' \
    -H 'Content-Type: application/json' \
    -H 'X-API-KEY: your_bugster_api_key' \
    -d '{
      "deployment_state": "success",
      "project_id": "my-project-1234567890",
      "organization_id": "org_abc123def456ghi789jkl",
      "commit_sha": "abc123def456",
      "environment_url": "https://your-app.example.com",
      "environment": "production"
    }'
  ```
</RequestExample>

## Required Parameters

<ParamField header="X-API-KEY" type="string" required>
  Your Bugster API key. Get this from **Settings > API Keys** in your Bugster dashboard.
</ParamField>

<ParamField body="project_id" type="string" required>
  Your Bugster project identifier. Find this in **Settings > General** of your project in your Bugster dashboard.
</ParamField>

<ParamField body="organization_id" type="string" required>
  Your Bugster organization identifier. Find this in **Settings > General** of your project in your Bugster dashboard.
</ParamField>

<ParamField body="environment_url" type="string" required>
  The URL where your application is deployed and where Bugster should run tests. Required when `deployment_state` is `"success"`.
</ParamField>

## Optional Parameters

<ParamField body="deployment_state" type="string" default="success">
  Current state of your deployment. Bugster only runs tests when set to `"success"`.

  **Possible values:**

  * `"success"` - Deployment completed successfully, trigger tests
  * `"in_progress"` - Deployment is still running, don't run tests
  * `"cancelled"` - Deployment was cancelled, don't run tests
  * `"error"` - Deployment failed, don't run tests
</ParamField>

<ParamField body="commit_sha" type="string">
  The Git commit SHA for this deployment. Use either `commit_sha` OR `branch`, not both.
</ParamField>

<ParamField body="branch" type="string">
  The Git branch name for this deployment. Use either `branch` OR `commit_sha`, not both.
</ParamField>

<ParamField body="environment" type="string" default="production">
  The deployment environment name (e.g., "production", "staging", "preview").
</ParamField>

## Response

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "processed",
    "message": "Custom integration event processed for org: org_abc123def456ghi789jkl, project: my-project-1234567890"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json Error theme={null}
  {
    "status": "error",
    "message": "Invalid project_id",
    "code": "INVALID_PROJECT"
  }
  ```
</ResponseExample>

## Prerequisites

<Warning>
  To use this integration, you must:

  1. Install the [Bugster GitHub App](https://github.com/apps/bugster-dev)
  2. Select the repository you want to integrate
  3. Commit the `.bugster` folder to the branch you're deploying

  Without these prerequisites, the webhook will not trigger test runs.
</Warning>

## Integration Steps

<Steps>
  <Step title="Get your credentials">
    Navigate to your Bugster dashboard and collect:

    * **API Key**: Settings > API Keys
    * **Project ID**: Settings > General (in your project)
    * **Organization ID**: Settings > General (in your project)

    <Warning>
      Keep your API key secure. Never commit it to version control or expose it in client-side code.
    </Warning>
  </Step>

  <Step title="Add webhook to your deployment pipeline">
    Add the API call to your deployment script or CI/CD pipeline. The webhook should be called **after** your deployment succeeds and your application is accessible.

    <CodeGroup>
      ```bash Shell Script theme={null}
      #!/bin/bash
      # After successful deployment
      curl -X POST 'https://api.bugster.app/webhooks/integrations/custom' \
        -H 'Content-Type: application/json' \
        -H 'X-API-KEY: $BUGSTER_API_KEY' \
        -d '{
          "deployment_state": "success",
          "project_id": "'$PROJECT_ID'",
          "organization_id": "'$ORG_ID'",
          "branch": "'$GIT_BRANCH'",
          "environment_url": "'$DEPLOYMENT_URL'"
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.bugster.app/webhooks/integrations/custom', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-API-KEY': process.env.BUGSTER_API_KEY
        },
        body: JSON.stringify({
          deployment_state: 'success',
          project_id: process.env.PROJECT_ID,
          organization_id: process.env.ORG_ID,
          commit_sha: process.env.GIT_COMMIT,
          environment_url: process.env.DEPLOYMENT_URL,
          environment: 'production'
        })
      });
      ```

      ```python Python theme={null}
      import requests
      import os

      response = requests.post(
          'https://api.bugster.app/webhooks/integrations/custom',
          headers={
              'Content-Type': 'application/json',
              'X-API-KEY': os.environ['BUGSTER_API_KEY']
          },
          json={
              'deployment_state': 'success',
              'project_id': os.environ['PROJECT_ID'],
              'organization_id': os.environ['ORG_ID'],
              'commit_sha': os.environ['GIT_COMMIT'],
              'environment_url': os.environ['DEPLOYMENT_URL'],
              'environment': 'production'
          }
      )
      ```
    </CodeGroup>
  </Step>

  <Step title="Test the integration">
    Deploy your application and verify that:

    1. The webhook is called successfully
    2. Bugster receives the deployment notification
    3. Test runs appear in your Bugster dashboard

    <Check>
      You can monitor webhook calls in your Bugster dashboard under **Project Settings > Integrations**.
    </Check>
  </Step>
</Steps>

## Best Practices

<Tip>
  **Environment-specific testing**: Use the `environment` parameter to run different test suites for staging vs production deployments.
</Tip>

<Tip>
  **Error handling**: Always check the webhook response and implement retry logic for failed requests.
</Tip>

<Warning>
  **Only call on success**: Set `deployment_state` to `"success"` only when your deployment is complete and accessible. Bugster cannot test broken deployments.
</Warning>

## Example Implementations

See our [GCP Cloud Build integration guide](/integrations/cloud-build) for a real-world example of using the custom integration API.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Repository does not have .bugster configuration folder">
    **Error message:** `"Skipping event: Repository does not have .bugster configuration folder"`

    This means your repository is missing the `.bugster` folder with test configurations. To fix this:

    1. Run `bugster quickstart --api-key=YOUR_API_KEY` in your repository
    2. Follow the prompts to set up your test configuration
    3. Commit the generated `.bugster/` folder to your repository
    4. Redeploy and trigger the webhook again

    <Warning>
      The `.bugster` folder must be present in the repository branch you're deploying for tests to run.
    </Warning>
  </Accordion>

  <Accordion title="Tests not running after webhook call">
    * Verify `deployment_state` is set to `"success"`
    * Ensure `environment_url` is accessible and returns a valid response
    * Check that your API key, project ID, and organization ID are correct
    * Confirm the `.bugster` configuration folder exists in your repository
  </Accordion>

  <Accordion title="Authentication errors">
    * Confirm your API key is valid and hasn't expired
    * Ensure the `X-API-KEY` header is properly formatted
    * Check that your API key has the necessary permissions
  </Accordion>

  <Accordion title="Invalid project or organization">
    * Verify your project ID and organization ID in the Bugster dashboard
    * Ensure you're using the correct IDs for the environment you're targeting
  </Accordion>
</AccordionGroup>