Long-running operations and webhooks

Long-running work uses a durable operation instead of tying completion to one HTTP request. API keys need operations:write to start work and operations:read to inspect it.

Start and inspect

Send POST /v1/operations with a kind, its input, and an optional callback. Supported kinds are sponsor-detection, brand-discovery, and influencer-similar.

{
  "kind": "brand-discovery",
  "input": { "brandId": "00000000-0000-0000-0000-000000000000" },
  "callback": {
    "url": "https://example.com/webhooks/creator-eagle",
    "events": ["progress", "terminal"],
    "secret": "a-receiver-owned-secret",
    "payloadFormat": "event"
  }
}

The response contains an id, status, known progress, timestamps, and callback metadata. It never returns callback credentials or the callback path; only the endpoint origin is shown. Poll GET /v1/operations/{id} independently of callbacks. Terminal statuses are succeeded, failed, and canceled.

On success, follow result.ref (or call the MCP get-operation-result tool) to retrieve the completed task output.

Inspect physical webhook attempt state with GET /v1/operations/{id}/deliveries. It reports the stable event/delivery IDs, attempt count, next attempt, last HTTP status/error, and whether delivery succeeded or was abandoned.

Sign callbacks with a webhook secret

Set callback.secret to a high-entropy value owned by your webhook receiver. The same callback object works through the public API and MCP tools:

{
  "callback": {
    "url": "https://example.com/webhooks/creator-eagle",
    "events": ["progress", "terminal"],
    "secret": "${CREATOR_EAGLE_WEBHOOK_SECRET}"
  }
}

The secret is write-only: Creator Eagle encrypts it at rest and never returns it in operation responses, delivery inspection responses, or logs. It is separate from your Creator Eagle API key, MCP_INTERNAL_SECRET, and the deployment-owned WEBHOOK_SECRET_ENCRYPTION_KEY. Generate and store it in the receiving service's secret manager, then provide the same value whenever you start an operation whose callbacks that receiver must verify.

For every delivery, Creator Eagle sends X-Creator-Eagle-Signature as t=<unix-seconds>,v1=<hex-hmac>. Verify it against the exact raw request bytes before parsing JSON:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyCreatorEagleWebhook(
  rawBody: Buffer,
  signatureHeader: string,
  secret: string
) {
  const fields = new Map(
    signatureHeader.split(",").map((part) => part.split("=", 2) as [string, string])
  );
  const timestamp = fields.get("t");
  const signature = fields.get("v1");
  if (!timestamp || !/^\d+$/.test(timestamp) || !signature || !/^[a-f\d]{64}$/i.test(signature)) {
    return false;
  }

  // Five minutes is a typical replay window; choose one appropriate to your system.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(timestamp)
    .update(".")
    .update(rawBody)
    .digest();
  const supplied = Buffer.from(signature, "hex");
  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}

After signature verification, deduplicate processing with X-Creator-Eagle-Event-Id or the body-level id. Creator Eagle may retry the same logical event, so a valid signature does not imply that an event is new.

Watch from a terminal

From this repository:

export CREATOR_EAGLE_API_KEY=ce_...
bun run creator-eagle watch <operation-id>

Use --interval 10, --json, or --api-url https://... as needed. The command exits 0 for success, 1 for failure, and 2 for cancellation.

Webhook envelope and delivery

Webhook bodies are versioned. id is the logical event deduplication key and deliveryId is the stable physical delivery identity across retries.

{
  "version": "1.0",
  "id": "event-uuid",
  "deliveryId": "delivery-uuid",
  "type": "creator_eagle.operation.succeeded.v1",
  "occurredAt": "2026-08-28T12:00:00.000Z",
  "operation": {
    "id": "operation-uuid",
    "kind": "brand-discovery",
    "status": "succeeded",
    "progress": { "current": 25, "total": 25, "percent": 100 },
    "result": { "ref": "/v1/operations/operation-uuid/result" },
    "error": null
  }
}

Creator Eagle accepts HTTPS callback URLs only, rejects URL credentials/query parameters and private/reserved DNS answers, pins the screened address for delivery, does not follow redirects, uses a 10-second timeout, and caps the body at 32 KiB. Non-2xx responses and network failures retry with exponential backoff. Progress events are coalesced; one terminal logical event is created atomically, although its physical delivery may retry.

The signature covers t + "." + rawRequestBody using HMAC-SHA256. Event and delivery IDs are also sent in X-Creator-Eagle-Event-Id and X-Creator-Eagle-Delivery-Id.

Wake a Conductor session

Conductor's public session-message API requires bearer authentication and a { "message": "..." } body. Point the callback at its message endpoint, select the adapter, and provide a workspace-scoped or user API token:

{
  "url": "https://api.conductor.build/v0/sessions/SESSION_ID/messages",
  "events": ["terminal"],
  "payloadFormat": "conductor-message",
  "authorization": {
    "type": "bearer",
    "token": "CONDUCTOR_API_TOKEN"
  }
}

Creator Eagle encrypts the bearer token in the same AES-GCM credential envelope as an HMAC secret and never returns or logs it. The Conductor message contains the complete versioned event envelope and its deduplication ID. Prefer a least-privilege workspace-scoped token and rotate it if the receiving session or integration is retired.