Skip to main content
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.
The custom integration is the same API that powers our GitHub Actions integration behind the scenes.

​
API Endpoint

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"
  }'

​
Required Parameters

​
X-API-KEY
string
required
Your Bugster API key. Get this from Settings > API Keys in your Bugster dashboard.
​
project_id
string
required
Your Bugster project identifier. Find this in Project Settings > General in your Bugster dashboard.
​
organization_id
string
required
Your Bugster organization identifier. Available in Settings > Organization in your Bugster dashboard.
​
environment_url
string
required
The URL where your application is deployed and where Bugster should run tests. Required when deployment_state is "success".

​
Optional Parameters

​
deployment_state
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
​
commit_sha
string
The Git commit SHA for this deployment. Use either commit_sha OR branch, not both.
​
branch
string
The Git branch name for this deployment. Use either branch OR commit_sha, not both.
​
environment
string
default:"production"
The deployment environment name (e.g., “production”, “staging”, “preview”).

​
Response

{
  "status": "processed",
  "message": "Custom integration event processed for org: org_abc123def456ghi789jkl, project: my-project-1234567890"
}

{
  "status": "error",
  "message": "Invalid project_id",
  "code": "INVALID_PROJECT"
}

​
Prerequisites

You must have the Bugster GitHub App installed and connected to your repository before using this integration.
Visit your Bugster Dashboard → Project Settings → GitHub Integration to install the GitHub App if you haven’t already.

​
Integration Steps

1

Get your credentials

Navigate to your Bugster dashboard and collect:
  • API Key: Settings > API Keys
  • Project ID: Project Settings > General
  • Organization ID: Settings > Organization
Keep your API key secure. Never commit it to version control or expose it in client-side code.
2

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.
#!/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'"
  }'
3

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
You can monitor webhook calls in your Bugster dashboard under Project Settings > Integrations.

​
Best Practices

Environment-specific testing: Use the environment parameter to run different test suites for staging vs production deployments.
Error handling: Always check the webhook response and implement retry logic for failed requests.
Only call on success: Set deployment_state to "success" only when your deployment is complete and accessible. Bugster cannot test broken deployments.

​
Example Implementations

See our GCP Cloud Build integration guide for a real-world example of using the custom integration API.

​
Troubleshooting

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
The .bugster folder must be present in the repository branch you’re deploying for tests to run.
  • 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
  • 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
  • Verify your project ID and organization ID in the Bugster dashboard
  • Ensure you’re using the correct IDs for the environment you’re targeting