Developer docs/Extension reference

Events index

All 38 core events: 34 domain events (published after the fact, observe only) and 4 pre-events (run before the action; 4 can be cancelled, 3 can be modified). On top of these, every mutating API request is a cancellable, modifiable event, see Cancel and modify. Rendered from pelty_extensions::events::REGISTRY; the test crates/pelty-api/tests/event_registry_coverage.rs fails when the source emits an event or payload key missing here. Machine-readable: events.json.

#How events work

Domain events (invoice.paid, …) are published after the action committed. Addons receive them through on-event when listed in capabilities.events, and as after:<event> / finished:<event> hooks. Webhook plugins receive them as signed HTTPS POSTs when listed in the manifest hooks. They cannot be cancelled or changed.
Pre-events (order.before_place, …) run synchronously in the before phase, in priority order. Each listener may continue, modify the payload, or cancel. A cancel answers the API call with HTTP 409 error.addon_hook_cancelled.
Request events <METHOD> <route> exist for every POST, PUT, PATCH and DELETE route, with all four phases. See Cancel and modify.
Custom events <addon-id>:<name> are emitted by addons (capabilities.emits) and have the same phases; listeners can cancel or modify them in before.
Listeners run lowest priority first (lowest 0, low 50, normal 100, high 150, highest 200, or any integer -1000..1000), ties by addon id. monitor (1000) runs last and only observes. See Hooks and mixins.

#Categories

Affiliate1 event Chat1 event Client1 event Customer1 event Invoice8 events Login1 event Order7 events Payment3 events Payment method1 event Quote1 event Service7 events Ticket3 events User3 events

#All events

Cancellable only

Event	Category	Phases	Cancel	Modify	Payload
`user.registered`	User	after, finished	no	no	`user_id` `via`
`user.logged_in`	User	after, finished	no	no	`user_id`
`user.login_alert`	User	after, finished	no	no	`user_id` `ip` `user_agent`
`customer.closed`	Customer	after, finished	no	no	`customer_id`
`order.created`	Order	after, finished	no	no	`order_id` `customer_id` `total` `currency`
`order.approved`	Order	after, finished	no	no	`order_id` `services` `auto`
`order.cancelled`	Order	after, finished	no	no	`order_id` `fraud`
`order.refunded`	Order	after, finished	no	no	`order_id` `credit_note_id`
`order.fraud_review`	Order	after, finished	no	no	`order_id` `customer_id` `score`
`order.fraud_rejected`	Order	after, finished	no	no	`order_id` `customer_id` `score`
`invoice.created`	Invoice	after, finished	no	no	`invoice_id` `customer_id` `service_id` `renewal` `on_demand` `late_fee_for` `debit_for` `number` `project_id` `billable`
`invoice.paid`	Invoice	after, finished	no	no	`invoice_id` `customer_id`
`invoice.voided`	Invoice	after, finished	no	no	`invoice_id`
`invoice.cancelled`	Invoice	after, finished	no	no	`invoice_id` `reason`
`invoice.refunded`	Invoice	after, finished	no	no	`invoice_id` `credit_note_id` `refund_id` `amount`
`invoice.due_soon`	Invoice	after, finished	no	no	`invoice_id` `customer_id` `days_left`
`invoice.overdue`	Invoice	after, finished	no	no	`invoice_id` `customer_id` `days_overdue`
`payment.succeeded`	Payment	after, finished	no	no	`invoice_id` `payment_id` `gateway` `provider_ref` `autopay`
`payment.failed`	Payment	after, finished	no	no	`invoice_id` `payment_id` `gateway` `provider_ref` `autopay` `attempt`
`payment.disputed`	Payment	after, finished	no	no	`gateway` `provider_ref` `payment_id` `event_type`
`payment_method.expiring`	Payment method	after, finished	no	no	`payment_method_id` `customer_id`
`service.created`	Service	after, finished	no	no	`service_id` `order_id`
`service.provisioned`	Service	after, finished	no	no	`service_id` `action` `module`
`service.provision_failed`	Service	after, finished	no	no	`service_id` `action` `error`
`service.suspended`	Service	after, finished	no	no	`service_id` `from` `reason`
`service.unsuspended`	Service	after, finished	no	no	`service_id` `from` `reason`
`service.terminated`	Service	after, finished	no	no	`service_id` `from` `reason` `provisioned`
`service.cancelled`	Service	after, finished	no	no	`service_id`
`ticket.opened`	Ticket	after, finished	no	no	`ticket_id` `number`
`ticket.replied`	Ticket	after, finished	no	no	`ticket_id` `by_staff`
`ticket.closed`	Ticket	after, finished	no	no	`ticket_id` `reason`
`chat.started`	Chat	after, finished	no	no	`chat_id` `name` `email`
`quote.sent`	Quote	after, finished	no	no	`quote_id`
`affiliate.payout_requested`	Affiliate	after, finished	no	no	`affiliate_id` `payout_id` `amount` `currency`
`login.before`	Login	before	yes	no	`email` `ip` `user_agent`
`client.before_register`	Client	before	yes	yes	`email` `display_name` `ip`
`order.before_place`	Order	before	yes	yes	`customer_id` `currency` `items` `coupon`
`invoice.before_create`	Invoice	before	yes	yes	`customer_id` `currency` `finalize` `items`

#Affiliate

#affiliate.payout_requested

An affiliate asked for a payout.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`affiliate_id`	`uuid`	yes	Affiliate
`payout_id`	`uuid`	yes	Payout
`amount`	`decimal`	yes	Amount
`currency`	`string`	yes	ISO 4217 code

Emitted from: crates/pelty-api/src/routes/affiliates.rs:163.

JSON

{
  "affiliate_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "amount": "12.50",
  "currency": "EUR",
  "payout_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "affiliate.payout_requested"
    ],
    "hooks": [
      {
        "event": "finished:affiliate.payout_requested",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "affiliate.payout_requested" {
        let affiliate_id = payload["affiliate_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:affiliate.payout_requested", affiliate_id);
    }
}

#Chat

#chat.started

A visitor started a live chat.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`chat_id`	`uuid`	yes	Chat
`name`	`string`	no	Visitor name
`email`	`string`	no	Visitor email

Emitted from: crates/pelty-api/src/routes/live_chat.rs:60.

JSON

{
  "chat_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "email": "[email protected]",
  "name": "…"
}

JSON

{
  "capabilities": {
    "events": [
      "chat.started"
    ],
    "hooks": [
      {
        "event": "finished:chat.started",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "chat.started" {
        let chat_id = payload["chat_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:chat.started", chat_id);
    }
}

#Client

#client.before_register

Before a sign-up. Cancel to refuse it; display_name may be rewritten. The password never leaves the host.

Kind	Phases	Cancellable	Modifiable	Since
pre-event	`before`	yes	yes	0.1.0

Payload

Key	Type	Always present	Description
`email`	`string`	yes	Submitted email
`display_name`	`string`	yes	Display name (modifiable)
`ip`	`string`	no	Client IP

Modifiable keys (everything else in a modify is ignored)

Key	Rule
`display_name`	String of at most 200 bytes; anything else keeps the submitted name

Emitted from: crates/pelty-api/src/routes/auth.rs:113.

JSON

{
  "display_name": "…",
  "email": "[email protected]",
  "ip": "203.0.113.7"
}

JSON

{
  "capabilities": {
    "hooks": [
      {
        "event": "client.before_register",
        "fail_open": true,
        "priority": "normal",
        "timeout_ms": 500
      }
    ]
  }
}

Rust

// op `hook`, phase `before`: return proceed, modify or cancel.
fn hook(input: &Value) -> Value {
    if input["event"] != "client.before_register" || input["cancelled"] == true {
        return reply::proceed();
    }
    let mut p = input["payload"].clone();
    // Cancel: the caller gets HTTP 409 `error.addon_hook_cancelled`.
    if p["email"].as_str().is_some_and(|v| v.ends_with(".invalid")) {
        return reply::cancel("refused by my-addon");
    }
    // Modify: only the keys listed under "Modifiable keys" are read back.
    p["display_name"] = json!(p["display_name"].as_str().unwrap_or("").trim());
    reply::modify(p)
}

#Customer

#customer.closed

A customer account was closed (GDPR erasure or admin close).

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`customer_id`	`uuid`	yes	Customer

Emitted from: crates/pelty-api/src/security.rs:370.

JSON

{
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "customer.closed"
    ],
    "hooks": [
      {
        "event": "finished:customer.closed",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "customer.closed" {
        let customer_id = payload["customer_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:customer.closed", customer_id);
    }
}

#Invoice

#invoice.created

An invoice was issued (order, renewal, late fee, debit note, project or billable items).

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`invoice_id`	`uuid`	yes	Invoice
`customer_id`	`uuid`	no	Customer
`service_id`	`uuid`	no	Renewed service
`renewal`	`bool`	no	Renewal invoice
`on_demand`	`bool`	no	Renewal requested early by the client
`late_fee_for`	`uuid`	no	Overdue invoice the fee is for
`debit_for`	`uuid`	no	Invoice the debit note corrects
`number`	`string`	no	Invoice number
`project_id`	`uuid`	no	Project
`billable`	`bool`	no	From billable items

Emitted from: crates/pelty-api/src/overdue.rs:38, crates/pelty-api/src/routes/billing.rs:214, crates/pelty-api/src/routes/billing.rs:671, crates/pelty-api/src/routes/billing.rs:700, crates/pelty-api/src/routes/billing.rs:772, crates/pelty-api/src/routes/credit.rs:147, crates/pelty-api/src/routes/projects.rs:126, crates/pelty-api/src/routes/renewals.rs:65, crates/pelty-api/src/routes/service_changes.rs:98, crates/pelty-api/src/worker.rs:40, crates/pelty-api/src/worker.rs:53.

JSON

{
  "billable": true,
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "debit_for": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "invoice_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "late_fee_for": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "number": "…",
  "on_demand": true,
  "project_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "renewal": true,
  "service_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "invoice.created"
    ],
    "hooks": [
      {
        "event": "finished:invoice.created",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "invoice.created" {
        let invoice_id = payload["invoice_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:invoice.created", invoice_id);
    }
}

#invoice.paid

An invoice became fully paid (gateway, credit, autopay or admin).

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`invoice_id`	`uuid`	yes	Invoice
`customer_id`	`uuid`	no	Customer (only on checkout auto-paid invoices)

Emitted from: crates/pelty-api/src/autopay.rs:115, crates/pelty-api/src/routes/billing.rs:219, crates/pelty-api/src/routes/billing.rs:830, crates/pelty-api/src/routes/bulk.rs:63, crates/pelty-api/src/routes/credit.rs:53, crates/pelty-api/src/routes/credit.rs:76, crates/pelty-api/src/routes/webhooks.rs:161.

JSON

{
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "invoice_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "invoice.paid"
    ],
    "hooks": [
      {
        "event": "finished:invoice.paid",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "invoice.paid" {
        let invoice_id = payload["invoice_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:invoice.paid", invoice_id);
    }
}

#invoice.voided

An invoice was voided.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`invoice_id`	`uuid`	yes	Invoice

Emitted from: crates/pelty-api/src/routes/billing.rs:723, crates/pelty-api/src/routes/bulk.rs:109.

JSON

{
  "invoice_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "invoice.voided"
    ],
    "hooks": [
      {
        "event": "finished:invoice.voided",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "invoice.voided" {
        let invoice_id = payload["invoice_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:invoice.voided", invoice_id);
    }
}

#invoice.cancelled

An unpaid invoice was cancelled by automation.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`invoice_id`	`uuid`	yes	Invoice
`reason`	`string`	yes	Why, e.g. `overdue_auto_cancel`

Emitted from: crates/pelty-api/src/overdue.rs:53.

JSON

{
  "invoice_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "reason": "…"
}

JSON

{
  "capabilities": {
    "events": [
      "invoice.cancelled"
    ],
    "hooks": [
      {
        "event": "finished:invoice.cancelled",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "invoice.cancelled" {
        let invoice_id = payload["invoice_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:invoice.cancelled", invoice_id);
    }
}

#invoice.refunded

A payment on the invoice was refunded.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`invoice_id`	`uuid`	yes	Invoice
`credit_note_id`	`uuid`	no	Credit note
`refund_id`	`uuid`	no	Refund
`amount`	`decimal`	no	Refunded amount

Emitted from: crates/pelty-api/src/routes/billing.rs:746, crates/pelty-api/src/routes/refunds.rs:164, crates/pelty-api/src/routes/store.rs:489.

JSON

{
  "amount": "12.50",
  "credit_note_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "invoice_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "refund_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "invoice.refunded"
    ],
    "hooks": [
      {
        "event": "finished:invoice.refunded",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "invoice.refunded" {
        let invoice_id = payload["invoice_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:invoice.refunded", invoice_id);
    }
}

#invoice.due_soon

Daily reminder: an invoice is due in a few days.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`invoice_id`	`uuid`	yes	Invoice
`customer_id`	`uuid`	yes	Customer
`days_left`	`int`	yes	Days until due

Emitted from: crates/pelty-api/src/approval.rs:77.

JSON

{
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "days_left": 3,
  "invoice_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "invoice.due_soon"
    ],
    "hooks": [
      {
        "event": "finished:invoice.due_soon",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "invoice.due_soon" {
        let invoice_id = payload["invoice_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:invoice.due_soon", invoice_id);
    }
}

#invoice.overdue

Daily reminder: an invoice is past due.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`invoice_id`	`uuid`	yes	Invoice
`customer_id`	`uuid`	yes	Customer
`days_overdue`	`int`	yes	Days past due

Emitted from: crates/pelty-api/src/overdue.rs:35.

JSON

{
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "days_overdue": 3,
  "invoice_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "invoice.overdue"
    ],
    "hooks": [
      {
        "event": "finished:invoice.overdue",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "invoice.overdue" {
        let invoice_id = payload["invoice_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:invoice.overdue", invoice_id);
    }
}

#invoice.before_create

Before an admin creates an invoice. Line descriptions may be rewritten; amounts only with money.modify.

Kind	Phases	Cancellable	Modifiable	Since
pre-event	`before`	yes	yes	0.1.0

Payload

Key	Type	Always present	Description
`customer_id`	`uuid`	yes	Customer
`currency`	`string`	yes	ISO 4217 code
`finalize`	`bool`	yes	Issue immediately
`items`	`array`	yes	`{description, quantity, unit_price}` lines (decimals as strings)

Modifiable keys (everything else in a modify is ignored)

Key	Rule
`items[].description`	Non-blank string of at most 500 bytes, matched by position; otherwise the original line text
`items[].unit_price`	Needs `capabilities.money.modify`; an exact decimal string (at most 4 places), audited as `addon.money_modified`. Without the capability the change is reverted

Emitted from: crates/pelty-api/src/routes/billing.rs:623.

JSON

{
  "currency": "EUR",
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "finalize": true,
  "items": []
}

JSON

{
  "capabilities": {
    "hooks": [
      {
        "event": "invoice.before_create",
        "fail_open": true,
        "priority": "normal",
        "timeout_ms": 500
      }
    ]
  }
}

Rust

// op `hook`, phase `before`: return proceed, modify or cancel.
fn hook(input: &Value) -> Value {
    if input["event"] != "invoice.before_create" || input["cancelled"] == true {
        return reply::proceed();
    }
    let mut p = input["payload"].clone();
    // Cancel: the caller gets HTTP 409 `error.addon_hook_cancelled`.
    if p["customer_id"].as_str().is_some_and(|v| v.ends_with(".invalid")) {
        return reply::cancel("refused by my-addon");
    }
    // Modify: rewrite `description` on every `items` element.
    if let Some(lines) = p["items"].as_array_mut() {
        for l in lines {
            l["description"] = json!(l["description"].as_str().unwrap_or("").trim());
        }
    }
    reply::modify(p)
}

Before a password sign-in is checked. Cancel to refuse the login (the client gets 409 error.addon_hook_cancelled). The payload is read-only: changes are ignored.

Kind	Phases	Cancellable	Modifiable	Since
pre-event	`before`	yes	no	0.1.0

Payload

Key	Type	Always present	Description
`email`	`string`	yes	Submitted email
`ip`	`string`	no	Client IP
`user_agent`	`string`	no	Browser user agent

Modifiable keys: none. A modify reply is accepted but the host does not read anything back.

Emitted from: crates/pelty-api/src/routes/auth.rs:151.

JSON

{
  "email": "[email protected]",
  "ip": "203.0.113.7",
  "user_agent": "…"
}

JSON

{
  "capabilities": {
    "hooks": [
      {
        "event": "login.before",
        "fail_open": true,
        "priority": "normal",
        "timeout_ms": 500
      }
    ]
  }
}

Rust

// op `hook`, phase `before`: return proceed, modify or cancel.
fn hook(input: &Value) -> Value {
    if input["event"] != "login.before" || input["cancelled"] == true {
        return reply::proceed();
    }
    let mut p = input["payload"].clone();
    // Cancel: the caller gets HTTP 409 `error.addon_hook_cancelled`.
    if p["email"].as_str().is_some_and(|v| v.ends_with(".invalid")) {
        return reply::cancel("refused by my-addon");
    }
    reply::proceed() // this event is read-only: a modify is ignored
}

#Order

#order.created

A customer placed an order.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`order_id`	`uuid`	yes	Order
`customer_id`	`uuid`	yes	Customer
`total`	`decimal`	yes	Order total
`currency`	`string`	yes	ISO 4217 code

Emitted from: crates/pelty-api/src/routes/billing.rs:212.

JSON

{
  "currency": "EUR",
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "order_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "total": "12.50"
}

JSON

{
  "capabilities": {
    "events": [
      "order.created"
    ],
    "hooks": [
      {
        "event": "finished:order.created",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "order.created" {
        let order_id = payload["order_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:order.created", order_id);
    }
}

#order.approved

An order was accepted and its services created.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`order_id`	`uuid`	yes	Order
`services`	`array`	yes	Created service ids
`auto`	`bool`	no	Approved automatically on payment

Emitted from: crates/pelty-api/src/approval.rs:17, crates/pelty-api/src/routes/billing.rs:498, crates/pelty-api/src/routes/store.rs:441.

JSON

{
  "auto": true,
  "order_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "services": []
}

JSON

{
  "capabilities": {
    "events": [
      "order.approved"
    ],
    "hooks": [
      {
        "event": "finished:order.approved",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "order.approved" {
        let order_id = payload["order_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:order.approved", order_id);
    }
}

#order.cancelled

An order was cancelled.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`order_id`	`uuid`	yes	Order
`fraud`	`bool`	no	Cancelled by the fraud check

Emitted from: crates/pelty-api/src/routes/billing.rs:535, crates/pelty-api/src/routes/bulk.rs:216.

JSON

{
  "fraud": true,
  "order_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "order.cancelled"
    ],
    "hooks": [
      {
        "event": "finished:order.cancelled",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "order.cancelled" {
        let order_id = payload["order_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:order.cancelled", order_id);
    }
}

#order.refunded

A paid order was refunded with a credit note.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`order_id`	`uuid`	yes	Order
`credit_note_id`	`uuid`	yes	Credit note

Emitted from: crates/pelty-api/src/routes/store.rs:490.

JSON

{
  "credit_note_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "order_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "order.refunded"
    ],
    "hooks": [
      {
        "event": "finished:order.refunded",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "order.refunded" {
        let order_id = payload["order_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:order.refunded", order_id);
    }
}

#order.fraud_review

The fraud check held an order for review.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`order_id`	`uuid`	yes	Order
`customer_id`	`uuid`	yes	Customer
`score`	`decimal`	yes	Fraud score

Emitted from: crates/pelty-api/src/routes/billing.rs:207.

JSON

{
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "order_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "score": "12.50"
}

JSON

{
  "capabilities": {
    "events": [
      "order.fraud_review"
    ],
    "hooks": [
      {
        "event": "finished:order.fraud_review",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "order.fraud_review" {
        let order_id = payload["order_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:order.fraud_review", order_id);
    }
}

#order.fraud_rejected

The fraud check rejected an order.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`order_id`	`uuid`	yes	Order
`customer_id`	`uuid`	yes	Customer
`score`	`decimal`	yes	Fraud score

Emitted from: crates/pelty-api/src/routes/billing.rs:202.

JSON

{
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "order_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "score": "12.50"
}

JSON

{
  "capabilities": {
    "events": [
      "order.fraud_rejected"
    ],
    "hooks": [
      {
        "event": "finished:order.fraud_rejected",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "order.fraud_rejected" {
        let order_id = payload["order_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:order.fraud_rejected", order_id);
    }
}

#order.before_place

Before an order is placed. Cancel to refuse; coupon may be set or cleared.

Kind	Phases	Cancellable	Modifiable	Since
pre-event	`before`	yes	yes	0.1.0

Payload

Key	Type	Always present	Description
`customer_id`	`uuid`	yes	Customer
`currency`	`string`	yes	ISO 4217 code
`items`	`array`	yes	Cart lines
`coupon`	`string`	no	Coupon code (modifiable)

Modifiable keys (everything else in a modify is ignored)

Key	Rule
`coupon`	Non-empty string of at most 64 bytes sets the code, `null` removes it, any other value keeps the submitted code. The code is then validated like a typed one

Emitted from: crates/pelty-api/src/routes/billing.rs:171.

JSON

{
  "coupon": "…",
  "currency": "EUR",
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "items": []
}

JSON

{
  "capabilities": {
    "hooks": [
      {
        "event": "order.before_place",
        "fail_open": true,
        "priority": "normal",
        "timeout_ms": 500
      }
    ]
  }
}

Rust

// op `hook`, phase `before`: return proceed, modify or cancel.
fn hook(input: &Value) -> Value {
    if input["event"] != "order.before_place" || input["cancelled"] == true {
        return reply::proceed();
    }
    let mut p = input["payload"].clone();
    // Cancel: the caller gets HTTP 409 `error.addon_hook_cancelled`.
    if p["customer_id"].as_str().is_some_and(|v| v.ends_with(".invalid")) {
        return reply::cancel("refused by my-addon");
    }
    // Modify: only the keys listed under "Modifiable keys" are read back.
    p["coupon"] = json!(p["coupon"].as_str().unwrap_or("").trim());
    reply::modify(p)
}

#Payment

#payment.succeeded

A payment was captured.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`invoice_id`	`uuid`	no	Invoice
`payment_id`	`uuid`	no	Payment
`gateway`	`string`	no	Gateway id
`provider_ref`	`string`	no	Gateway reference
`autopay`	`bool`	no	Charged by autopay

Emitted from: crates/pelty-api/src/autopay.rs:113, crates/pelty-api/src/routes/billing.rs:825, crates/pelty-api/src/routes/bulk.rs:61, crates/pelty-api/src/routes/credit.rs:51, crates/pelty-api/src/routes/credit.rs:74, crates/pelty-api/src/routes/webhooks.rs:156, crates/pelty-api/src/routes/webhooks.rs:168.

JSON

{
  "autopay": true,
  "gateway": "stripe",
  "invoice_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "payment_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "provider_ref": "…"
}

JSON

{
  "capabilities": {
    "events": [
      "payment.succeeded"
    ],
    "hooks": [
      {
        "event": "finished:payment.succeeded",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "payment.succeeded" {
        let invoice_id = payload["invoice_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:payment.succeeded", invoice_id);
    }
}

#payment.failed

A payment attempt failed.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`invoice_id`	`uuid`	no	Invoice
`payment_id`	`uuid`	no	Payment
`gateway`	`string`	no	Gateway id
`provider_ref`	`string`	no	Gateway reference
`autopay`	`bool`	no	Autopay attempt
`attempt`	`int`	no	Autopay attempt number

Emitted from: crates/pelty-api/src/autopay.rs:128, crates/pelty-api/src/routes/webhooks.rs:175.

JSON

{
  "attempt": 3,
  "autopay": true,
  "gateway": "stripe",
  "invoice_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "payment_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "provider_ref": "…"
}

JSON

{
  "capabilities": {
    "events": [
      "payment.failed"
    ],
    "hooks": [
      {
        "event": "finished:payment.failed",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "payment.failed" {
        let invoice_id = payload["invoice_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:payment.failed", invoice_id);
    }
}

#payment.disputed

A gateway reported a chargeback or dispute.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`gateway`	`string`	yes	Gateway id
`provider_ref`	`string`	yes	Gateway reference
`payment_id`	`uuid`	no	Payment
`event_type`	`string`	no	Gateway event type

Emitted from: crates/pelty-api/src/routes/webhooks.rs:124.

JSON

{
  "event_type": "…",
  "gateway": "stripe",
  "payment_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "provider_ref": "…"
}

JSON

{
  "capabilities": {
    "events": [
      "payment.disputed"
    ],
    "hooks": [
      {
        "event": "finished:payment.disputed",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "payment.disputed" {
        let gateway = payload["gateway"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:payment.disputed", gateway);
    }
}

#Payment method

#payment_method.expiring

A saved card expires soon.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`payment_method_id`	`uuid`	yes	Payment method
`customer_id`	`uuid`	yes	Customer

Emitted from: crates/pelty-api/src/autopay.rs:64.

JSON

{
  "customer_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "payment_method_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "payment_method.expiring"
    ],
    "hooks": [
      {
        "event": "finished:payment_method.expiring",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "payment_method.expiring" {
        let payment_method_id = payload["payment_method_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:payment_method.expiring", payment_method_id);
    }
}

#Quote

#quote.sent

A quote was sent to a customer.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`quote_id`	`uuid`	yes	Quote

Emitted from: crates/pelty-api/src/routes/quotes.rs:158.

JSON

{
  "quote_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "quote.sent"
    ],
    "hooks": [
      {
        "event": "finished:quote.sent",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "quote.sent" {
        let quote_id = payload["quote_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:quote.sent", quote_id);
    }
}

#Service

#service.created

A service was created from an order.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`service_id`	`uuid`	yes	Service
`order_id`	`uuid`	yes	Order

Emitted from: crates/pelty-api/src/approval.rs:19, crates/pelty-api/src/routes/billing.rs:503, crates/pelty-api/src/routes/store.rs:443.

JSON

{
  "order_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "service_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "service.created"
    ],
    "hooks": [
      {
        "event": "finished:service.created",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "service.created" {
        let service_id = payload["service_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:service.created", service_id);
    }
}

#service.provisioned

A provisioning module action succeeded.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`service_id`	`uuid`	yes	Service
`action`	`string`	yes	`create`, `suspend`, …
`module`	`string`	yes	Module id

Emitted from: crates/pelty-api/src/provision.rs:120.

JSON

{
  "action": "…",
  "module": "…",
  "service_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "service.provisioned"
    ],
    "hooks": [
      {
        "event": "finished:service.provisioned",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "service.provisioned" {
        let service_id = payload["service_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:service.provisioned", service_id);
    }
}

#service.provision_failed

A provisioning module action failed.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`service_id`	`uuid`	yes	Service
`action`	`string`	yes	Module action
`error`	`string`	yes	Error message

Emitted from: crates/pelty-api/src/provision.rs:142.

JSON

{
  "action": "…",
  "error": "…",
  "service_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "service.provision_failed"
    ],
    "hooks": [
      {
        "event": "finished:service.provision_failed",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "service.provision_failed" {
        let service_id = payload["service_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:service.provision_failed", service_id);
    }
}

#service.suspended

A service was suspended.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`service_id`	`uuid`	yes	Service
`from`	`string`	no	Previous status
`reason`	`string`	no	Why

Emitted from: crates/pelty-api/src/overdue.rs:42, crates/pelty-api/src/routes/billing.rs:899, crates/pelty-api/src/routes/refunds.rs:151.

JSON

{
  "from": "…",
  "reason": "…",
  "service_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "service.suspended"
    ],
    "hooks": [
      {
        "event": "finished:service.suspended",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "service.suspended" {
        let service_id = payload["service_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:service.suspended", service_id);
    }
}

#service.unsuspended

A service was reactivated.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`service_id`	`uuid`	yes	Service
`from`	`string`	no	Previous status
`reason`	`string`	no	Why

Emitted from: crates/pelty-api/src/overdue.rs:65, crates/pelty-api/src/routes/billing.rs:900.

JSON

{
  "from": "…",
  "reason": "…",
  "service_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "service.unsuspended"
    ],
    "hooks": [
      {
        "event": "finished:service.unsuspended",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "service.unsuspended" {
        let service_id = payload["service_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:service.unsuspended", service_id);
    }
}

#service.terminated

A service was terminated.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`service_id`	`uuid`	yes	Service
`from`	`string`	no	Previous status
`reason`	`string`	no	Why
`provisioned`	`bool`	no	The module terminated it remotely

Emitted from: crates/pelty-api/src/overdue.rs:50, crates/pelty-api/src/routes/billable.rs:131, crates/pelty-api/src/routes/billing.rs:901.

JSON

{
  "from": "…",
  "provisioned": true,
  "reason": "…",
  "service_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "service.terminated"
    ],
    "hooks": [
      {
        "event": "finished:service.terminated",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "service.terminated" {
        let service_id = payload["service_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:service.terminated", service_id);
    }
}

#service.cancelled

A cancellation request was applied.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`service_id`	`uuid`	yes	Service

Emitted from: crates/pelty-api/src/routes/billing.rs:902, crates/pelty-api/src/routes/service_changes.rs:63.

JSON

{
  "service_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "service.cancelled"
    ],
    "hooks": [
      {
        "event": "finished:service.cancelled",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "service.cancelled" {
        let service_id = payload["service_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:service.cancelled", service_id);
    }
}

#Ticket

#ticket.opened

A support ticket was opened.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`ticket_id`	`uuid`	yes	Ticket
`number`	`string`	no	Ticket number

Emitted from: crates/pelty-api/src/routes/tickets.rs:308.

JSON

{
  "number": "…",
  "ticket_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "ticket.opened"
    ],
    "hooks": [
      {
        "event": "finished:ticket.opened",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "ticket.opened" {
        let ticket_id = payload["ticket_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:ticket.opened", ticket_id);
    }
}

#ticket.replied

A reply was posted on a ticket.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`ticket_id`	`uuid`	yes	Ticket
`by_staff`	`bool`	yes	Reply came from staff

Emitted from: crates/pelty-api/src/routes/tickets.rs:352, crates/pelty-api/src/routes/tickets.rs:588.

JSON

{
  "by_staff": true,
  "ticket_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "ticket.replied"
    ],
    "hooks": [
      {
        "event": "finished:ticket.replied",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "ticket.replied" {
        let ticket_id = payload["ticket_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:ticket.replied", ticket_id);
    }
}

#ticket.closed

A ticket was closed.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`ticket_id`	`uuid`	yes	Ticket
`reason`	`string`	no	Why, e.g. `inactive`

Emitted from: crates/pelty-api/src/routes/support.rs:418.

JSON

{
  "reason": "…",
  "ticket_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "ticket.closed"
    ],
    "hooks": [
      {
        "event": "finished:ticket.closed",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "ticket.closed" {
        let ticket_id = payload["ticket_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:ticket.closed", ticket_id);
    }
}

#User

#user.registered

A new account was created (password sign-up, SSO or OAuth).

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`user_id`	`uuid`	yes	New user
`via`	`string`	no	SSO/OAuth provider id when not a password sign-up

Emitted from: crates/pelty-api/src/oauth.rs:285, crates/pelty-api/src/routes/auth.rs:132, crates/pelty-api/src/saml.rs:354.

JSON

{
  "user_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e",
  "via": "…"
}

JSON

{
  "capabilities": {
    "events": [
      "user.registered"
    ],
    "hooks": [
      {
        "event": "finished:user.registered",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "user.registered" {
        let user_id = payload["user_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:user.registered", user_id);
    }
}

#user.logged_in

A user signed in successfully.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`user_id`	`uuid`	yes	User

Emitted from: crates/pelty-api/src/routes/auth.rs:203.

JSON

{
  "user_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "user.logged_in"
    ],
    "hooks": [
      {
        "event": "finished:user.logged_in",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "user.logged_in" {
        let user_id = payload["user_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:user.logged_in", user_id);
    }
}

Sign-in from a new IP for an account with login alerts on.

Kind	Phases	Cancellable	Modifiable	Since
domain event	`after`, `finished`	no	no	0.1.0

Payload

Key	Type	Always present	Description
`user_id`	`uuid`	yes	User
`ip`	`string`	yes	Client IP
`user_agent`	`string`	yes	Browser user agent

Emitted from: crates/pelty-api/src/routes/auth.rs:340.

JSON

{
  "ip": "203.0.113.7",
  "user_agent": "…",
  "user_id": "0190f7a2-6c1e-7b3a-9d2e-4f5a6b7c8d9e"
}

JSON

{
  "capabilities": {
    "events": [
      "user.login_alert"
    ],
    "hooks": [
      {
        "event": "finished:user.login_alert",
        "priority": "monitor"
      }
    ]
  }
}

Rust

// on-event: delivered after the action was committed (cannot be cancelled).
fn on_event(name: &str, payload: &Value) {
    if name == "user.login_alert" {
        let user_id = payload["user_id"].as_str().unwrap_or_default();
        let _ = host::kv_set("last:user.login_alert", user_id);
    }
}

#Custom addon events

Named <addon-id>:<event>, declared in capabilities.emits and emitted with pelty_addon_sdk::emit. They are not in the registry because addons define them. Other addons listen with before:<id>:<event> (cancel or modify), after: or finished: in hooks. An emit inside a listener nests; the depth is limited to 4. The emitter gets {cancelled, reason, payload} back. See Events and hooks for a full example.

#Lifecycle phases

Phases in order: before, during, after, finished. Source: crates/pelty-api/src/addon_events.rs.

before: synchronous, in priority order; listeners may modify the payload or cancel it (uncancel too when ignore_cancelled). monitor listeners only observe. Money and secret rules apply.
during: delivered while the action runs (concurrently, observe only).
after: the action succeeded; the result is in the payload.
finished: always last, with status = ok | failed | cancelled.

#Webhook plugins

A webhook plugin lists domain events in its manifest hooks. Each one is POSTed to webhook_url, signed, with the payload above. Delivery attempts are listed under Admin, Plugins, Deliveries.

Field	Type	Required	Description
`id`	`String`	yes
`name`	`String`	yes
`version`	`String`	yes
`api_version`	`u32`	yes
`description`	`String`	no
`capabilities`	`Vec<String>`	no
`hooks`	`Vec<String>`	no
`webhook_url`	`Option<String>`	no	External plugins only: HTTPS endpoint receiving signed events.
`settings_schema`	`Option<serde_json::Value>`	no	Optional JSON-schema-like description of admin settings.
`ui`	`PluginUi`	no	UI contributions rendered by the frontend in named slots.

Source: crates/pelty-extensions/src/plugins.rs (PluginManifest).

JSON

{
  "api_version": 1,
  "hooks": [
    "invoice.paid",
    "order.created"
  ],
  "id": "my-plugin",
  "name": "My plugin",
  "version": "1.0.0",
  "webhook_url": "https://example.com/pelty"
}

Generated by pelty-docs from the PeltyCMS source. View as Markdown

Events index

#How events work

#Categories

#All events

#Affiliate

#affiliate.payout_requested

#Chat

#chat.started

#Client

#client.before_register

#Customer

#customer.closed

#Invoice

#invoice.created

#invoice.paid

#invoice.voided

#invoice.cancelled

#invoice.refunded

#invoice.due_soon

#invoice.overdue

#invoice.before_create

#Login

#login.before

#Order

#order.created

#order.approved

#order.cancelled

#order.refunded

#order.fraud_review

#order.fraud_rejected

#order.before_place

#Payment

#payment.succeeded

#payment.failed

#payment.disputed

#Payment method

#payment_method.expiring

#Quote

#quote.sent

#Service

#service.created

#service.provisioned

#service.provision_failed

#service.suspended

#service.unsuspended

#service.terminated

#service.cancelled

#Ticket

#ticket.opened

#ticket.replied

#ticket.closed

#User

#user.registered

#user.logged_in

#user.login_alert

#Custom addon events

#Lifecycle phases

#Webhook plugins