Answers to common questions and solutions for issues you may encounter when using the BetaTesting API and webhooks.
Frequently Asked Questions
API Access
How do I get API access?
The API is available on Enterprise plans. Contact your BetaTesting account manager or our sales team to enable API access for your company. Once enabled, you can create API credentials from your Company Settings > Integrations page.
Who can manage API credentials and webhooks?
Only Full Admin users on your company account can access the Integrations page to create, edit, or delete API clients and webhooks.
Can I have multiple API clients?
Yes. You can have up to 1 static API key and up to 5 OAuth2 clients per company. Each client has its own credentials and can be deleted independently.
Where is the full API documentation?
Interactive Swagger documentation with complete endpoint specs, request/response schemas, and example payloads is available from your Company Settings > Integrations page. Click View API Documentation to access it.
Authentication
What's the difference between a static API key and OAuth2?
A static API key is a single permanent token that grants full read and write access. OAuth2 client credentials let you generate short-lived access tokens with configurable scopes (read-only, write-only, or both). OAuth2 is recommended for production applications.
My API key starts with btst_ - is that correct?
Yes. Static API keys always begin with the btst_ prefix. This is expected and is how BetaTesting identifies the authentication method.
I lost my API key / client secret. Can I recover it?
No. Credentials are displayed once at creation time and cannot be retrieved later. Delete the existing client and create a new one.
Can I restrict API access by IP address?
Yes. Contact your BetaTesting account manager to configure an IP allowlist for your API clients. Requests from non-allowed IPs will receive a 403 Forbidden response.
Webhooks
How many webhooks can I create?
The default settings allow up to 3 webhooks per company. Each can have a different URL and subscribe to different events. Contact your BetaTesting account team if you need more.
Do I need to use HTTPS for my webhook URL?
Yes. Webhook endpoints must use HTTPS. BetaTesting does not deliver to plain HTTP URLs.
Can I receive the same event on multiple webhooks?
Yes. If multiple webhooks subscribe to the same event, each one receives its own delivery independently.
How do I know if a webhook delivery is a retry?
Each event delivery has a unique X-BetaTesting-Event-ID header. If you receive the same Event ID more than once, it's a retry of a previously failed delivery. Use this ID to deduplicate on your end.
What happens if my webhook endpoint is down?
BetaTesting retries failed deliveries up to 4 times over approximately 2.5 hours (1 min, 5 min, 30 min, 2 hours). After 5 total attempts, the delivery is marked as failed.
I rotated my webhook secret - do I need to update my verification code?
Yes. After rotating the signing secret, your server must use the new secret for signature verification. The old secret is invalidated immediately.
Troubleshooting
401 Unauthorized
Possible causes:
Invalid or expired token - Verify your API key or OAuth2 access token is correct and not expired. If using OAuth2, request a new access token.
Deleted API client - The API client may have been deleted from the Integrations page. Check that it still exists.
Incorrect header format - Ensure the
Authorizationheader uses the formatBearer YOUR_TOKEN(with a space after "Bearer").Expired client - If your account manager set an expiration date on the client, it may have expired. Create a new client or contact your account manager.
403 Forbidden
Possible causes:
Insufficient scope - Your OAuth2 token may not have the required scope.
GETrequests needapi:read;POST,PATCH, andDELETErequests needapi:write. Request a new token with the correct scopes.IP not allowed - If an IP allowlist is configured, requests from non-listed IPs are blocked. Contact your account manager to update the allowlist.
API access not enabled - Your company's subscription may not include API access. Contact your account manager.
404 Not Found
Possible causes:
Wrong resource ID - Verify the test ID, tester ID, issue ID, etc. is correct
Resource belongs to a different company - The API only returns resources belonging to the company associated with your API client
Resource was deleted - The resource may have been removed
422 Validation Error
Possible causes:
Invalid enum value - Check that status, priority, and other enum fields use the values listed in the API documentation. The error message will include the valid options.
Missing required field - The request body is missing a required parameter
Invalid data type - A field has the wrong type (e.g., string instead of integer)
429 Too Many Requests
You've exceeded your rate limit. Check the Retry-After response header for the number of seconds to wait before retrying. Write endpoints have a stricter limit (30 requests/minute) than read endpoints.
Solutions:
Add delays between requests in batch operations
Cache responses for data that doesn't change frequently
Use the
Retry-Afterheader to wait the correct amount of time
Webhooks Not Delivering
Possible causes:
Webhook is disabled - Check the Integrations page to verify the webhook is active
Event not subscribed - Verify the webhook is subscribed to the event type you're expecting
Endpoint unreachable - Ensure your server is accessible from the public internet on HTTPS
Endpoint timing out - Your server must respond within 10 seconds. Return a
200immediately and process the event asynchronously.Endpoint returning non-2xx - Your server must return a
2xxstatus code to acknowledge delivery. Check your server logs for errors.
Webhook Signature Verification Failing
Possible causes:
Wrong secret - Ensure you're using the correct signing secret for the specific webhook endpoint. If you rotated the secret, update your verification code.
Modified payload - The signature is computed over the raw request body. If your framework parses the JSON before you verify, use the raw body string instead.
Timestamp mismatch - Ensure you're extracting the
tvalue from the signature header correctly and including it in the signed payload string.Encoding issue - The signed payload format is
{timestamp}.{raw_json_body}. Ensure there are no extra whitespace characters or encoding differences.
Getting Help
If you're experiencing an issue not covered here, contact your BetaTesting account manager. When reporting API issues, include:
The full URL of the request
The HTTP method and status code
The response body (error message)
The
X-BetaTesting-Event-IDheader (for webhook issues)Your API client name (never share the actual token/secret)