Developer docs/Extension reference

Cancel and modify

Everything an addon can stop or change before it happens, and exactly what it may change. There are three kinds: typed pre-events, request events on every mutating API route, and mixins.

#Rules

• Only the before phase can cancel or modify. during, after and finished only observe (the reply is ignored).
• Listeners run in priority order. Each sees the payload as changed by the ones before it, and input.cancelled tells it whether an earlier listener cancelled.
• After a cancel, later listeners are skipped unless their hook sets ignore_cancelled: true. Only those may reply uncancel, which clears the cancel.
• monitor listeners always run last and cannot change anything; a non-continue reply is logged and ignored.
• A cancel answers the API call with HTTP 409 and error.addon_hook_cancelled. The reason (at most 200 characters) is logged, not shown to the user.
• If a hook errors or times out (timeout_ms, default 500, capped by the sandbox), fail_open: true (default) continues and fail_open: false blocks the action with 409 error.addon_hook_failed.
• A modify must be a JSON object. The host reads back only the keys listed for the event; other keys are ignored.
• Money keys (amount, price, unit_price, total, subtotal, tax, tax_total, discount, setup_fee, recurring_amount, credit, fee, balance, amount_paid) change only for addons with capabilities.money.modify, must be exact decimal strings (at most 4 places), and every change is audited as addon.money_modified. Without the capability the money keys are reverted and the rest of the change is kept.
• Secrets never reach addons: password, current_password, new_password, password_confirmation, secret, client_secret, token, api_key, totp, otp, mfa_code, recovery_code, card_number, cvc, cvv and any key ending in _password, _secret or _token are replaced by "[redacted]" and restored afterwards, so they can be neither read nor changed.

#Reply format

{"action":"continue"}
{"action":"modify","payload":{ "coupon": "SUMMER" }}
{"action":"cancel","reason":"not allowed"}
{"action":"uncancel"}

The Rust SDK builds these with reply::proceed(), reply::modify(p), reply::cancel(reason) and reply::uncancel().

#Typed pre-events

#Example: cancel, modify and uncancel

/// Pre-events and lifecycle phases listed in `capabilities.hooks` call op
/// `hook`. Return `proceed`, `modify(payload)` or `cancel(reason)`.
fn hook(input: &Value) -> Value {
    let event = input["event"].as_str().unwrap_or("");
    if input["phase"].as_str().unwrap_or("before") != "before" {
        return reply::proceed(); // during/after/finished only observe
    }
    let mut p = input["payload"].clone();
    bump(&format!("hook:{event}"));
    match event {
        // Cancel: refuse sign-in for one domain.
        "login.before" if p["email"].as_str().is_some_and(|e| e.ends_with("@denied.test")) => reply::cancel("domain not allowed"),
        // Modify: tidy up the display name before the account is created.
        "client.before_register" => {
            p["display_name"] = json!(p["display_name"].as_str().unwrap_or("").trim().to_string());
            reply::modify(p)
        }
        // Own custom event (declared as `before:integration-guide:greeted`,
        // delivered with `event` = the bare name and `phase` = "before").
        "integration-guide:greeted" if p["name"] == "nobody" => reply::cancel("no greeting for nobody"),
        "order.before_place" => order_hook(input, p),
        _ => reply::proceed(),
    }
}

/// `order.before_place` with `ignore_cancelled: true` and priority `highest`:
/// this runs even after an earlier addon cancelled the order. `uncancel` is
/// only honoured for such hooks. Here: always allow orders using the
/// `GUIDE-VIP` coupon, and normalise coupon codes to upper case (`coupon` is
/// the only key the host reads back from this event).
fn order_hook(input: &Value, mut p: Value) -> Value {
    let coupon = p["coupon"].as_str().unwrap_or("").trim().to_uppercase();
    if input["cancelled"] == true {
        return if coupon == "GUIDE-VIP" { reply::uncancel() } else { reply::proceed() };
    }
    if coupon.is_empty() {
        return reply::proceed();
    }
    p["coupon"] = json!(coupon);
    reply::modify(p)
}

#Request events (every mutating route)

Every POST, PUT, PATCH and DELETE under /api/v1 (except addon routes) is an event named <METHOD> <route template>. A hook before:<METHOD> <route> gets {method, path, route, query, body} and may cancel the request or rewrite body (the JSON request body, at most 1 MiB, money and secret rules apply). Patterns: before:* (every request), before:POST /api/v1/admin/* (prefix), or an exact template. Because they see every request, these hooks are a dangerous capability (hooks.any) the admin must approve at install. during, after (with the JSON response) and finished (with status and http_status) observe.

{
  "capabilities": {
    "hooks": [
      {
        "event": "before:POST /api/v1/client/tickets",
        "priority": "high"
      },
      {
        "event": "after:PUT /api/v1/client/profile",
        "priority": "monitor"
      }
    ]
  }
}

459 cancellable request events:

#Mixins

A mixin wraps one core route under /api/v1 (any method, GET too; not /api/v1/auth/* or addon routes): before rewrites the request body, after rewrites the JSON response (only values of keys it already has), around does both with shared state, and return replaces the response with one of the same shape. Mixins need admin approval (mixins, mixins.return) and can be switched off per addon. See Hooks and mixins.

/// Mixins wrap a core route (`capabilities.mixins`). An `after` mixin may
/// change values of keys the response already has; new keys are dropped.
fn mixin(input: &Value) -> Value {
    let mut resp = input["response"].clone();
    // Opt-in per request so this example never changes other callers.
    let wanted = input["request"]["query"].as_str().unwrap_or("").contains("guide=1");
    if input["at"] == "after" && wanted {
        if let Some(c) = resp["city"].as_str() {
            resp["city"] = json!(c.to_uppercase());
        }
        return json!({ "response": resp });
    }
    json!({})
}