Connect to Litmus over MCP

An order request a user creates in Litmus itself, or through another integration, never produces an event for you. Events start with the order request's submission; a draft produces none. If your endpoint is registered after an order request was submitted, you receive events from the next change on.

{
  "type": "order_request.stage_changed",
  "timestamp": "2026-10-21T12:00:00Z",
  "data": {
    "order_request_id": "7d1a6b2e-3c4f-4a5b-9e8d-1f2a3b4c5d6e",
    "stage": "sourcing_quotes",
    "previous_stage": "in_review",
    "action_required": false,
    "message": "Litmus is asking labs that can run this order for quotes.",
    "url": "https://platform.litmus.science/order-requests/7d1a6b2e-3c4f-4a5b-9e8d-1f2a3b4c5d6e"
  }
}

{
  "type": "order_request.quote_received",
  "timestamp": "2026-10-21T12:00:00Z",
  "data": {
    "order_request_id": "7d1a6b2e-3c4f-4a5b-9e8d-1f2a3b4c5d6e",
    "stage": "sourcing_quotes",
    "previous_stage": null,
    "action_required": true,
    "message": "Quotes are coming in for this order. Sign in to compare labs and pick one to move forward with.",
    "url": "https://platform.litmus.science/order-requests/7d1a6b2e-3c4f-4a5b-9e8d-1f2a3b4c5d6e"
  }
}

{
  "type": "integration.test",
  "timestamp": "2026-10-21T12:00:00Z",
  "data": {
    "source": "Litmus",
    "test": true
  }
}

The data fields of both order_request.* events:

order_request.quote_received normally arrives while the order is sourcing_quotes (a lab can still quote until the order is paid, so stage reports the order's stage at the time) and sets action_required to true: the user signs in to compare labs and pick one. The order request object has a later results stage; no event is sent for it yet.

Use a Standard Webhooks library for your stack rather than checking the signature by hand. Reply with any 2xx status once you have stored the event; the response body is ignored.

from fastapi import FastAPI, Request, Response
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = FastAPI()
# The whsec_... secret you gave Litmus. Your own config, never in client code.
webhook = Webhook(LITMUS_WEBHOOK_SECRET)

@app.post("/litmus/webhooks")
async def litmus_webhook(request: Request) -> Response:
    headers = {
        name: request.headers[name]
        for name in ("webhook-id", "webhook-timestamp", "webhook-signature")
    }
    try:
        # Verifies the signature over the raw body and the timestamp's freshness,
        # then returns the parsed body: {"type", "timestamp", "data"}.
        event = webhook.verify(await request.body(), headers)
    except WebhookVerificationError:
        return Response(status_code=401)

    # Litmus may deliver an event more than once; the id is the same each time.
    if await already_handled(headers["webhook-id"]):
        return Response(status_code=200)
    await handle_litmus_event(event)  # keep this quick; reply within 10 s
    return Response(status_code=200)

Events are ordered per order request: an event is not sent while an older event for the same order request is still awaiting delivery, so a retrying event holds back the ones after it for that order until it is delivered or passes the horizon. Events for different order requests are independent. A crash between a delivery and its acknowledgement can send an event again under the same webhook-id, which is why delivery is at least once.

The URL is stored in normalised form: the host is lowercased, a default port is dropped and a bare host gets a trailing slash, so https://Example.com is stored and called as https://example.com/. Paths and query strings are kept as given. Only https is accepted. Events are only recorded while both the URL and the secret are set; see which orders produce events.