Overview
Webhooks allow Preclinical to notify your systems when test runs complete. Instead of polling the API, you receive an HTTP POST request with run results as soon as they’re available. Use cases for webhooks:- Trigger deployment pipelines based on test results
- Post results to Slack or other communication tools
- Update dashboards and monitoring systems
- Store historical results in your own database
Configuration
Webhooks can be configured at two levels:| Level | Description |
|---|---|
| Organization | Default webhook for all agents in your organization |
| Agent | Override the org webhook for a specific agent |
Organization Webhook
- Go to Settings in the sidebar
- Click the Webhooks tab
- Enter your webhook URL
- Optionally enter a signing secret (recommended)
- Click Save
Agent-Level Webhook
To configure a webhook for a specific agent:- Go to Agents in the sidebar
- Click on the agent you want to configure
- Click Edit
- Scroll to the Webhook section
- Enter the webhook URL and optional secret
- Click Save
Agent-level webhooks override the organization webhook for that specific agent.
If an agent doesn’t have its own webhook configured, the organization webhook is used.
Webhook Payload
When a test run completes, Preclinical sends a POST request to your webhook URL with this payload:Payload Fields
| Field | Type | Description |
|---|---|---|
event | string | Event type (always test_run_completed) |
timestamp | string | ISO-8601 timestamp when the webhook was sent |
test_run.id | string | UUID of the test run |
test_run.test_run_id | string | Human-readable run ID (e.g., TR-00042) |
test_run.name | string | Name of the test run |
test_run.agent_id | string | UUID of the agent that was tested |
test_run.agent_name | string | Name of the agent |
test_run.status | string | Final status: completed, failed, or canceled |
test_run.pass_rate | number | Percentage of scenarios that passed (0-100) |
test_run.passed_count | number | Number of passing scenarios |
test_run.failed_count | number | Number of failing scenarios |
test_run.error_count | number | Number of scenarios that errored |
test_run.total_scenarios | number | Total number of scenarios in the run |
test_run.started_at | string | ISO-8601 timestamp when run started |
test_run.completed_at | string | ISO-8601 timestamp when run completed |
test_run.duration_seconds | number | Total run duration in seconds |
results_url | string | Direct link to view detailed results |
Signature Verification
If you configure a webhook secret, Preclinical signs each request so you can verify it came from us.Verifying Signatures
Python Example
Retry Behavior
If your webhook endpoint returns an error (non-2xx status code) or times out:| Retry | Delay |
|---|---|
| 1st | 1 minute |
| 2nd | 5 minutes |
| 3rd | 30 minutes |
Delivery History
View webhook delivery history to debug issues:- Go to Settings > Webhooks
- Click View Delivery History
- Timestamp
- HTTP status code
- Response time
- Request/response bodies (for debugging)
Example: Slack Notification
Best Practices
Respond Quickly
Return a 200 response immediately, then process the webhook asynchronously. This prevents timeouts.
Use Signature Verification
Always verify webhook signatures in production to ensure requests are authentic.
Handle Duplicates
Use the
test_run.id to deduplicate webhooks in case of retries.Monitor Failures
Check delivery history regularly to catch integration issues early.