Skip to main content
Webhooks let you receive real-time HTTP POST notifications from Miteos whenever something meaningful happens on your account — a task completes, an agent needs approval, a deployment goes live, or your credit balance runs low. Instead of polling the API, you register an endpoint and Miteos pushes events to you as they occur.

​
Registering a Webhook

Register a webhook endpoint from your API Keys dashboard or via the API. Specify the URL you want to receive events, the event types you care about, and an optional signing secret for verification: 
const webhook = await client.webhooks.create({
  url: 'https://your-app.com/webhooks/miteos',
  events: ['task.complete', 'approval.required', 'agent.error'],
  secret: 'whsec_your_signing_secret',
});

​
Event Types

Subscribe to only the events relevant to your integration. Every event is delivered as a POST request with a JSON body matching the payload format described below.
EventDescriptionWhen Triggered
task.createdA new task has been submitted.Immediately on task creation.
task.planningThe orchestrator is decomposing the task.After submission, before agents start.
task.runningAgents have started executing.When the first agent begins work.
task.completeAll agents have finished successfully.When deliverables are ready.
task.failedThe task failed with an unrecoverable error.On terminal failure.
agent.actionAn agent performed a tool call.On each tool execution.
agent.thinkingAn agent completed a reasoning step.On each thinking cycle.
agent.errorAn agent encountered an error.On agent-level error.
approval.requiredAn agent is waiting for human approval.When an action is gated by policy.
deployment.startedA deployment build has been triggered.On deploy trigger.
deployment.liveDeployment succeeded and the URL is live.When the deployment URL becomes active.
deployment.failedThe build or deployment failed.On deployment failure.
trading.order_placedA trade was executed by an agent.When a position is opened or closed.
trading.kill_triggeredThe safety kill switch was activated.When a configured limit is breached.
billing.credit_lowYour account credits are running low.When balance drops below 10%.

​
Payload Format

Every webhook event uses the same JSON envelope, regardless of event type. The data object contains event-specific fields: 
{
  "id": "evt_a1b2c3d4e5f6",
  "type": "task.complete",
  "created_at": "2026-06-18T10:45:00Z",
  "data": {
    "task_id": "task_x9y8z7w6v5",
    "status": "completed",
    "deliverables_count": 3,
    "total_cost": 0.12,
    "duration_seconds": 142
  }
}
​
id
string
A unique identifier for this event. Use it to deduplicate deliveries.
​
type
string
The event type, such as task.complete or agent.error.
​
created_at
string
ISO 8601 timestamp of when the event was generated.
​
data
object
Event-specific payload. The fields vary by event type.

​
Signature Verification

Every webhook request includes an X-Miteos-Signature header. You should always verify this signature before processing the payload — it proves the request came from Miteos and was not tampered with in transit. The header value is an HMAC-SHA256 hash of the raw request body, prefixed with sha256=: 
import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}
Use crypto.timingSafeEqual to prevent timing attacks. Pass the raw request body string — not a parsed JSON object — to ensure the hash matches exactly.
Always verify the X-Miteos-Signature header before trusting or acting on webhook data. Skipping verification exposes your endpoint to spoofed requests.

​
Retry Policy

If your endpoint returns a non-2xx status code or does not respond within 5 seconds, Miteos retries the delivery with exponential backoff:
AttemptDelay
1Immediate
230 seconds
32 minutes
415 minutes
51 hour
After 5 failed attempts, the webhook is automatically disabled. You can re-enable it from the API Keys dashboard and replay missed events.
Return a 200 OK response as fast as possible — ideally within 500ms — and do all processing asynchronously. Enqueue the payload in a job queue or message broker and handle the business logic in a background worker.

​
Best Practices

  • Respond quickly — Return 200 within 5 seconds. Long-running processing should happen in a background job after you acknowledge receipt.
  • Handle duplicates — Use the event.id field as an idempotency key. In rare cases the same event may be delivered more than once.
  • Verify every signature — Always validate the X-Miteos-Signature header before acting on the payload, even in development.
  • Use HTTPS — Webhook URLs must use TLS. Plain HTTP endpoints are rejected.
  • Monitor delivery health — Check the webhook dashboard regularly for delivery failures, especially after deploying changes to your endpoint.