Webhooks

Webhooks allow you to receive real-time HTTP POST notifications when events occur in Mission Control. Configure webhook endpoints to integrate with external services, trigger automation, or monitor system activity.

Features

Event filtering: Subscribe to specific event types or all events (*)
HMAC signature verification: Cryptographically signed payloads using SHA-256
Automatic retries: Exponential backoff with jitter (30s, 5m, 30m, 2h, 8h)
Circuit breaker: Auto-disable after 5 consecutive failures
Delivery history: Track all webhook attempts with status codes and response bodies

List Webhooks

curl http://localhost:3000/api/webhooks \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('http://localhost:3000/api/webhooks', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});
const data = await response.json();

Response

array

Array of webhook configurations with delivery statistics

integer

Webhook ID

string

Webhook name

string

Target URL for webhook deliveries

string

Masked secret (shows only last 4 characters: ••••••abc1)

array

Array of subscribed event types (e.g., ["agent.status_change", "activity.task_created"] or ["*"] for all)

boolean

Whether webhook is active

integer

Number of consecutive delivery failures

boolean

true if circuit breaker is tripped (≥5 failures)

integer

Total delivery attempts

integer

Deliveries with 2xx status code

integer

Deliveries with errors or non-2xx status

Create Webhook

curl -X POST http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Slack Notifications",
    "url": "https://hooks.slack.com/services/T00/B00/XXX",
    "events": ["agent.error", "activity.task_created"],
    "generate_secret": true
  }'

const response = await fetch('http://localhost:3000/api/webhooks', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    name: 'Slack Notifications',
    url: 'https://hooks.slack.com/services/T00/B00/XXX',
    events: ['agent.error', 'activity.task_created'],
    generate_secret: true
  })
});
const data = await response.json();

Request Body

string

required

Webhook name for identification

string

required

Target URL (must be valid HTTP/HTTPS endpoint)

array

Event types to subscribe to. Use ["*"] for all events. Defaults to ["*"]

boolean

default:true

Generate HMAC secret for signature verification

Response

The secret field is only shown in full once during creation. Save it securely.

integer

Created webhook ID

string

HMAC secret (64-character hex string). Only shown on creation.

string

Confirmation message

Update Webhook

curl -X PUT http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "id": 1,
    "name": "Updated Name",
    "events": ["*"],
    "enabled": true,
    "reset_circuit": true
  }'

Request Body

integer

required

Webhook ID to update

string

New webhook name

string

New target URL

array

Updated event subscriptions

boolean

Enable or disable webhook

boolean

Generate a new HMAC secret (returns new secret in response)

boolean

Reset circuit breaker (clears failures and re-enables webhook)

Delete Webhook

curl -X DELETE http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"id": 1}'

Request Body

integer

required

Webhook ID to delete

Get Delivery History

Retrieve webhook delivery logs with status codes, error messages, and response bodies.

curl "http://localhost:3000/api/webhooks/deliveries?webhook_id=1&limit=50" \
  -H "x-api-key: YOUR_API_KEY"

Query Parameters

integer

Filter deliveries for a specific webhook

integer

default:50

Maximum deliveries to return (max 200)

integer

default:0

Pagination offset

Response

array

integer

Delivery ID

integer

Parent webhook ID

string

Event type (e.g., agent.status_change, test.ping)

integer

HTTP status code (e.g., 200, 500, null if timeout)

string

Error message if delivery failed

number

Request duration in milliseconds

integer

Retry attempt number (0 = first attempt)

boolean

Whether this is a retry of a previous failed delivery

integer

Unix timestamp

integer

Total delivery count

Retry Failed Delivery

Manually retry a failed webhook delivery.

curl -X POST http://localhost:3000/api/webhooks/retry \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"delivery_id": 123}'

Request Body

integer

required

ID of the failed delivery to retry

Response

boolean

Whether the retry succeeded

integer

HTTP status code from retry attempt

number

Request duration

Test Webhook

Send a test ping to verify webhook configuration.

curl -X POST http://localhost:3000/api/webhooks/test \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"id": 1}'

Request Body

integer

required

Webhook ID to test

Test Payload Example

{
  "event": "test.ping",
  "timestamp": 1678901234,
  "data": {
    "message": "This is a test webhook from Mission Control",
    "webhook_id": 1,
    "webhook_name": "My Webhook",
    "triggered_by": "admin"
  }
}

Signature Verification

All webhook payloads include an X-MC-Signature header containing an HMAC-SHA256 signature. Always verify this signature before processing webhooks.

Verification Algorithm

Extract the raw request body as a UTF-8 string (do not parse JSON first)
Read the X-MC-Signature header
Compute HMAC-SHA256 of the raw body using your webhook secret
Format as: sha256=<hex-digest>
Compare using constant-time comparison

Node.js Example

const crypto = require('crypto');

function verifySignature(secret, rawBody, signatureHeader) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  
  const sigBuf = Buffer.from(signatureHeader);
  const expBuf = Buffer.from(expected);
  
  if (sigBuf.length !== expBuf.length) return false;
  return crypto.timingSafeEqual(sigBuf, expBuf);
}

// Express middleware example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-mc-signature'];
  const rawBody = req.body.toString('utf8');
  
  if (!verifySignature(MY_SECRET, rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }
  
  const payload = JSON.parse(rawBody);
  // Process webhook...
  res.sendStatus(200);
});

Python Example

import hmac
import hashlib

def verify_signature(secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(expected, signature_header)

# Flask example
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-MC-Signature')
    raw_body = request.get_data()
    
    if not verify_signature(MY_SECRET, raw_body, signature):
        return 'Invalid signature', 401
    
    payload = request.get_json()
    # Process webhook...
    return '', 200

Retry Logic

Mission Control automatically retries failed webhook deliveries using exponential backoff:

Attempt	Delay	Total Time
1	immediate	0s
2	30s ±20%	~30s
3	5m ±20%	~5m
4	30m ±20%	~35m
5	2h ±20%	~2.5h
6	8h ±20%	~10.5h

Jitter (±20%) prevents thundering herd when multiple webhooks fail simultaneously.

Circuit Breaker

After 5 consecutive failures (across all retries), the webhook is automatically disabled. To re-enable:

Fix the endpoint issue
Call PUT /api/webhooks with reset_circuit: true

Event Types

Subscribe to specific event types or use * for all events:

Agent Events

agent.status_change - Agent status changed (online, offline, busy, error)
agent.error - Agent entered error state

Task Events

activity.task_created - New task created
activity.task_updated - Task fields modified
activity.task_deleted - Task deleted
activity.task_status_changed - Task status changed

Activity Events

activity.<type> - Generic activity (e.g., activity.agent_created, activity.user_login)

Notification Events

notification.<type> - System notifications

Security Events

security.<action> - Security-related events (e.g., security.login_failed)

Test Events

test.ping - Test webhook delivery

Payload Format

All webhook deliveries use this structure:

{
  "event": "agent.status_change",
  "timestamp": 1678901234,
  "data": {
    "id": 42,
    "name": "researcher",
    "status": "online",
    "previous_status": "offline"
  }
}

Headers

Content-Type: application/json
User-Agent: MissionControl-Webhook/1.0
X-MC-Event: agent.status_change
X-MC-Signature: sha256=abc123...

Best Practices

Always verify signatures - Prevent spoofed webhooks
Respond quickly - Return 200 OK within 10 seconds (timeout)
Process async - Queue webhooks for background processing
Idempotency - Handle duplicate deliveries gracefully (retries)
Monitor failures - Alert on circuit breaker trips
Rotate secrets - Use regenerate_secret periodically

Rate Limits

Creation/updates: 100 requests/minute per API key
Delivery timeout: 10 seconds per webhook
Max retries: 5 attempts with exponential backoff
History retention: Last 200 deliveries per webhook

The automatic retry scheduler runs every 60 seconds and processes up to 50 pending retries per batch.

​Webhooks

​Features

​List Webhooks

​Response

​Create Webhook

​Request Body

​Response

​Update Webhook

​Request Body

​Delete Webhook

​Request Body

​Get Delivery History

​Query Parameters

​Response

​Retry Failed Delivery

​Request Body

​Response

​Test Webhook

​Request Body

​Test Payload Example

​Signature Verification

​Verification Algorithm

​Node.js Example

​Python Example

​Retry Logic

​Circuit Breaker

​Event Types

​Agent Events

​Task Events

​Activity Events

​Notification Events

​Security Events

​Test Events

​Payload Format

​Headers

​Best Practices

​Rate Limits

Webhooks

Features

List Webhooks

Response

Create Webhook

Request Body

Response

Update Webhook

Request Body

Delete Webhook

Request Body

Get Delivery History

Query Parameters

Response

Retry Failed Delivery

Request Body

Response

Test Webhook

Request Body

Test Payload Example

Signature Verification

Verification Algorithm

Node.js Example

Python Example

Retry Logic

Circuit Breaker

Event Types

Agent Events

Task Events

Activity Events

Notification Events

Security Events

Test Events

Payload Format

Headers

Best Practices

Rate Limits