Webhooks

Webhooks - Magica pushes events to your server

Webhooks let your server receive HTTP POST notifications for asynchronous model and workflow runs. Public REST consumers should verify the signature, respond quickly, and process events idempotently.

Delivery is powered by Svix: automatic retries, HMAC-SHA256 signatures, and delivery logging included.

Configure a webhook

Pass a webhook object when starting a model run or workflow run.

curl -X POST https://api.magica.com/api/v1/runs \
  -H "Authorization: Bearer $MAGICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "workflow-or-system-slug",
    "webhook": {
      "url": "https://your-app.com/webhooks/magica",
      "events": ["run.completed", "run.failed"],
      "metadata": { "orderId": "order_456" }
    }
  }'

For standalone model runs, include the same webhook object in POST /v1/nodes/{nodeType}/run.

Supported events

Model runs and workflow runs support different event sets.

Event	Model run	Workflow run	Description
`run.started`	Yes	Yes	The run started
`run.completed`	Yes	Yes	The run completed successfully
`run.failed`	Yes	Yes	The run failed
`run.canceled`	No	Yes	The workflow run was canceled
`node.completed`	No	Yes	One workflow node completed
`node.failed`	No	Yes	One workflow node failed

When you omit events, Magica sends every event supported by that run type.

Event payload

{
  "success": true,
  "type": "run.completed",
  "runId": "cuid_abc123",
  "workflowId": "cuid_def456",
  "data": { "status": "COMPLETED", "completedNodes": 5, "failedNodes": 0 },
  "metadata": { "orderId": "order_456" },
  "error": null,
  "createdAt": "2026-02-18T12:00:00.000Z"
}

Field	Type	Description
`success`	boolean	`true` for success events, `false` for failures
`type`	string	Event type, such as `run.completed`
`runId`	string	Execution run ID
`workflowId`	string	Workflow definition ID for workflow runs; node type for standalone model runs
`data`	object	Event-specific data
`metadata`	object \| null	Custom metadata echoed back by the execution surface
`error`	string \| null	Error message for failure events
`createdAt`	string	ISO 8601 timestamp

Event types

run.started

A run begins executing.

run.completed

All requested work finished successfully.

run.failed

One or more steps failed.

run.canceled

The run was canceled.

node.completed

A single node finished successfully.

node.failed

A single node failed.

Handler pattern

Always respond 200 OK immediately and process asynchronously. If your handler takes too long, Svix will retry and you may receive duplicate deliveries.

Node.js
Python

app.post("/webhooks/magica", (req, res) => {
  res.status(200).send("OK");

  const event = req.body;
  if (event.type === "run.completed") {
    enqueueResultProcessing(event.runId);
  }
  if (event.type === "run.failed") {
    logRunFailure(event.runId, event.error);
  }
});

@app.post("/webhooks/magica")
async def magica_webhook(request: Request):
    event = await request.json()

    if event["type"] == "run.completed":
        enqueue_result_processing(event["runId"])
    elif event["type"] == "run.failed":
        logger.error("Run failed: %s", event["error"])

    return {"ok": True}

Security

Every webhook is signed with HMAC-SHA256 via Svix. Verify signatures before trusting the payload:

Node.js
Python

import { Webhook } from "svix";

app.use("/webhooks/magica", express.raw({ type: "application/json" }));

const wh = new Webhook("whsec_your_signing_secret");

app.post("/webhooks/magica", (req, res) => {
  try {
    const payload = wh.verify(req.body, {
      "svix-id": req.headers["svix-id"],
      "svix-timestamp": req.headers["svix-timestamp"],
      "svix-signature": req.headers["svix-signature"],
    });
    res.status(200).send("OK");
    enqueueWebhook(payload);
  } catch (err) {
    res.status(400).send("Invalid signature");
  }
});

from svix.webhooks import Webhook, WebhookVerificationError

wh = Webhook("whsec_your_signing_secret")

@app.post("/webhooks/magica")
async def magica_webhook(request: Request):
    body = await request.body()
    try:
        payload = wh.verify(body, dict(request.headers))
    except WebhookVerificationError:
        return Response(status_code=400, content="Invalid signature")

    enqueue_webhook(payload)
    return Response(status_code=200, content="OK")

Overview

Workflows

Models

Nodes

Runs

System Workflows

Credits

Media Library

Bug Reports

Configure a webhook

Supported events

Event payload

Event types

run.started

run.completed

run.failed

run.canceled

node.completed

node.failed

Handler pattern

Security

​Configure a webhook

​Supported events

​Event payload

​Event types

run.started

run.completed

run.failed

run.canceled

node.completed

node.failed

​Handler pattern

​Security

Configure a webhook

Supported events

Event payload

Event types

Handler pattern

Security