Create a notification rule
Tells people by email when something needs them, such as a dispute decision coming due, reconciliation breaks, a proposal waiting for approval, or the top-up chargeback rate passing a threshold. Webhooks still carry events to your systems; this is for people.
Authentication
A secret key (rl_sk_test_..., rl_sk_live_...) or a restricted key with limited scopes (rl_rk_test_..., rl_rk_live_...). A restricted key can carry agent: true and an expires_at, and is what a coding agent should hold. Keys end in a checksum so secret scanners can recognize them. People create, roll and revoke keys in the dashboard; GET /v1/api_keys lists them, masked.
Headers
Send true to see what the write would do without doing it. The response is the normal body with dry_run: true, changes (path, before, after), warnings and errors added, and nothing is stored. Validation runs as it would for a real write. The request is kept in request logs, tagged Dry run. When the same change is then made for real, its audit event has dry_run_preceded: true.
Request
What can notify people. dispute.decision_due fires lead_time before a dispute’s deadline. proposal.pending fires when a config proposal needs approval. topup_chargeback.threshold_exceeded fires when the top-up chargeback rate or the credits at risk pass the rule’s threshold. margin_guardrail.breached fires when work falls below a margin guardrail’s floor. catalog.price_changed fires when Runledger publishes a new price version for a catalog model one of your cost models uses. auto_top_up.disabled fires when a customer’s auto top-up stops after repeated failed payments. Notification rules are for your team. Alerts about a customer’s own balance or limits (balance.low, usage.threshold_reached, spend_limit.threshold_reached) are webhook events sent to your endpoints, and Runledger never emails your end customers.
How the notification is delivered. The set is open and new channels may be added. Built in: email, which needs recipients, and webhook, which needs webhook_endpoint. Handle a channel you don’t recognise by its name.
email only: up to 20 addresses.
webhook only: the webhook endpoint (ID) that receives the notification.
dispute.decision_due only: how long before the deadline to send it, as an ISO 8601 duration. Default PT24H.
For topup_chargeback.threshold_exceeded. Send at least one. There is no default. Runledger applies no threshold you haven’t set, and you choose the level for your own history.
topup_chargeback.threshold_exceeded only: watch one provider. Leave out to watch the whole account.
Response
What can notify people. dispute.decision_due fires lead_time before a dispute’s deadline. proposal.pending fires when a config proposal needs approval. topup_chargeback.threshold_exceeded fires when the top-up chargeback rate or the credits at risk pass the rule’s threshold. margin_guardrail.breached fires when work falls below a margin guardrail’s floor. catalog.price_changed fires when Runledger publishes a new price version for a catalog model one of your cost models uses. auto_top_up.disabled fires when a customer’s auto top-up stops after repeated failed payments. Notification rules are for your team. Alerts about a customer’s own balance or limits (balance.low, usage.threshold_reached, spend_limit.threshold_reached) are webhook events sent to your endpoints, and Runledger never emails your end customers.
email, webhook, or a channel added later. The set is open.
email only.
webhook only.
For topup_chargeback.threshold_exceeded. Send at least one. There is no default. Runledger applies no threshold you haven’t set, and you choose the level for your own history.
Who made a change. Runledger fills it in from the credential, so a client can’t claim to be someone else: an API key always acts as itself, the dashboard calls the API as the signed-in person, and the MCP server passes the client’s name and the person it acts for. A request that sends a Runledger-Actor header is refused with 400 parameter_unknown.