Webhooks

Webhooks - Magica pushes events to your server

Webhooks let your server receive HTTP POST notifications for asynchronous standalone model 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.

curl -X POST https://inference.magica.com/v1/nodes/nano_banana_pro/run \
  -H "Authorization: Bearer $MAGICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subModelId": "nano-banana-pro-text",
    "input": {
      "prompt": "A cinematic product photo of a glass speaker"
    },
    "webhook": {
      "url": "https://your-app.com/webhooks/magica",
      "events": ["run.completed", "run.failed"],
      "metadata": { "orderId": "order_456" }
    }
  }'

The 202 response includes the accepted runId. When webhook is present, it also includes webhook.signingSecret. Store that whsec_... value in your server’s secret manager and use it to verify every delivery to this endpoint. Magica does not persist or log the signing secret. Reusing the same destination returns the same endpoint secret so deployments can safely retry registration.

Supported events

Event	Description
`run.started`	The run started
`run.completed`	The run completed successfully
`run.failed`	The run failed
`run.canceled`	The run was canceled

When you omit events, Magica sends every event supported by model runs.

Event payload

{
  "success": true,
  "type": "run.completed",
  "runId": "cuid_abc123",
  "workflowId": "nano_banana_pro",
  "data": { "status": "COMPLETED" },
  "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	Model `nodeType` for a standalone model run
`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

When a run fails because its model was retired, data.replacedBy names the model ID to use instead, when one is known. GET /v1/nodes/runs/{runId} returns the same replacedBy field.

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.

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. The signing secret is returned in the 202 response as webhook.signingSecret; it is different from your Magica API key and from any custom headers you send. 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

Models

Standalone Model Runs

LLM Gateway

Credits

Generated Media

Configure a webhook

Supported events

Event payload

Event types

run.started

run.completed

run.failed

run.canceled

Handler pattern

Security