Webhooks

Receiving Agent Callbacks via Webhooks

Agents communicate results back to Mission Control by calling a webhook endpoint. If you’re building a custom agent or integrating Mission Control into an external system, understanding the webhook protocol is essential.

The Callback Endpoint

Agents POST to:

POST /api/webhooks/callback

This endpoint is public-facing — agents running on remote machines need to be able to reach it. In a local setup, this is http://localhost:4000/api/webhooks/callback.

Payload Structure

A webhook callback payload looks like:

{
  "taskId": "abc123",
  "agentId": "agent-1",
  "type": "progress",
  "message": "Completed database migration, running tests",
  "timestamp": "2025-01-15T10:30:00Z"
}

For completion callbacks, type is "complete" and a summary field is included. For failures, type is "error" and an error field describes what went wrong.

HMAC Signature Verification

Every webhook request must include a signature in the X-Signature-SHA256 header:

X-Signature-SHA256: sha256=<hex-digest>

The signature is computed as HMAC-SHA256 over the raw request body, using the webhook secret configured in Mission Control’s settings.

Mission Control rejects any webhook request with a missing or invalid signature with a 401 Unauthorized response. This prevents unauthorized parties from injecting fake activity events or falsely completing tasks.

Computing the Signature

To sign a webhook payload in Node.js:

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', webhookSecret)
  .update(rawBody)
  .digest('hex');
// Set header: `sha256=${signature}`

Retry Behavior

If Mission Control returns a non-2xx response, agents are expected to retry with exponential backoff. The recommended retry schedule is: 5s, 30s, 2m, 10m. After four failed attempts, the callback should be abandoned and the failure logged.

Registering External Webhooks

In addition to receiving agent callbacks, Mission Control can also send webhooks to external URLs when task state changes. Configure outbound webhooks in Settings > Webhooks.