Webhooks

Magic sends an HTTP POST to your project's webhook URL when a request changes or a conversation message is added or updated. Each project has one webhook URL.

Go to the project page, enter an HTTPS URL in the Webhook section, and click Save.

Event types

• status_change — the request record changed.
• message — a conversation message was added or updated.

Every event contains the latest request state and the complete conversation, not only the field or message that changed.

Payload

{
    "type": "status_change",
    "request_id": "7aa99eb1-04cd-4d7f-954f-bd23a713bf73",
    "internal_id": "workspace-task-id",
    "status": "COMPLETED",
    "title": "Research competitor pricing",
    "completed_at": "2026-10-01T08:30:00.000Z",
    "result": "The comparison is complete. The requested objective was met.",
    "metadata": {
        "cancellation_reason": null,
        "overview": "The comparison is complete. The requested objective was met.",
        "notable_updates": null
    },
    "callback_meta": {
        "sessionKey": "customer-session-123",
        "channel": "gtd1"
    },
    "conversation": [
        {
            "id": "message-id",
            "request_id": "7aa99eb1-04cd-4d7f-954f-bd23a713bf73",
            "content": "I completed the comparison.",
            "attachments": [],
            "source_type": "ASSISTANT",
            "project_id": "project-id",
            "created_at": "2026-10-01T08:30:00.000Z"
        }
    ]
}

The public request status is one of PENDING, IN_PROGRESS, COMPLETED, or CANCELLED. There is no separate FAILED status. A COMPLETED request may still have an unmet objective, so inspect result and the conversation before treating it as successful. For cancelled requests, inspect metadata.cancellation_reason.

Authentication and verification

Webhook callbacks are not HMAC-signed and do not include a signature header.

For bearer-token verification, include a token in callback_meta when you create the request:

{
    "title": "Research competitor pricing",
    "instructions": "Compare our top three competitors.",
    "objective": "Return a pricing comparison table.",
    "callback_meta": {
        "token": "your-webhook-secret"
    }
}

Magic will then add this header to callbacks for that request:

Authorization: Bearer your-webhook-secret

The complete callback_meta object is also echoed in the payload. Use HTTPS, validate the bearer token with a constant-time comparison, and do not put unrelated secrets in callback_meta. If you do not provide a token, possession of the webhook URL is the only callback verification available.

Delivery behavior

Your endpoint should return a 2xx response. A failed delivery is attempted up to three times, with short delays between attempts. Because a callback can be delivered more than once, make your handler idempotent.

Multiple environments

Create a separate project for each environment and save a different webhook URL on each project. This keeps development and production requests, API keys, and callbacks isolated.