Skip to main content

Webhooks

Webhooks let you subscribe to FleetQ platform events and receive an HTTP POST to your endpoint when they occur. Use them to trigger downstream systems — update a CRM when a lead-research experiment completes, post to Slack when a project run fails, or kick off a CI pipeline when an agent finishes a code-review workflow.

Webhooks are outbound — FleetQ pushes events to your URL. For inbound data (receiving events from external systems), see Signals.

Core concepts

Webhook endpoint

A URL you own that accepts POST requests. Each endpoint is team-scoped and stores the target URL, an optional secret for HMAC-SHA256 signature verification, and a list of subscribed event types.

Event types

Subscribe to specific transitions — e.g. experiment.completed, experiment.killed, project_run.completed, approval.requested. Only events matching your subscription fire the webhook.

Payload

FleetQ sends a JSON payload containing the event type, timestamp, team ID, and the full resource object (experiment, project run, etc.) at the time of the event. The X-FleetQ-Signature header carries the HMAC-SHA256 signature if a secret is configured.

Retry behaviour

Failed deliveries (non-2xx or timeout) are retried up to 3 times with exponential backoff. Delivery attempts and response codes are logged for inspection.

Verifying signatures

If you configure a webhook secret, verify each delivery in your receiver:

Signature verification (PHP) 
$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_FLEETQ_SIGNATURE'] ?? '';
$expected  = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

MCP tools

Tool Description
webhook_list List all webhook endpoints for the team.
webhook_create Create a new webhook endpoint with URL, secret, and event subscriptions.
webhook_update Update URL, secret, or subscribed event types on an existing webhook.
webhook_delete Delete a webhook endpoint and stop all future deliveries.

REST API

Manage webhooks via the REST API at /api/v1/webhook-endpoints: GET, POST, PUT {id}, DELETE {id}. Full schema in the API Reference.

Related concepts

  • Signals — inbound webhook connector for receiving events from external systems.
  • Outbound Delivery — multi-channel delivery (email, Slack, Telegram) with rate limiting.
  • Triggers — event-driven rules that launch projects when conditions are met.
  • Experiments — the primary source of experiment.* webhook events.