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

{
  "status": "processed",
  "message": "Custom integration event processed for org: org_abc123def456ghi789jkl, project: my-project-1234567890"
}
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"
}

​
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