App dashboard guide
How app developers use the ATM dashboard to configure environments, modules, webhooks, secrets, fees, and delivery logs.
Compatible with the closed-beta ATM app APIs and versioned ATM event headers. Check atm-api-version on every webhook or XRPC receiver event.
Dashboard mental model
The app dashboard is the control plane for an app DID. It is not a separate identity: the same ATM profile can also be a payer or creator, but app-only controls stay in the app dashboard.
- Payments tab
- Creator or app revenue, payouts, disputes, reports, tax, and payment-account tools when the DID receives money.
- App tab
- App-specific configuration: modules, app fees, receivers, event logs, test/live config, and developer tools.
- Settings
- Profile, role upgrades, payment setup, contact/support, and account-level preferences.
Control-to-docs map
Every technical control in the app dashboard should have a matching docs path. Use this table when reviewing the dashboard before onboarding another app developer.
| App profile and app URL | App onboarding and App dashboard guide explain the ATM profile plus app-specific URL fields. |
|---|---|
| Test/live environment switcher | Testing and environments explains environment isolation, secrets, modules, and live promotion. |
| Module picker | App dashboard guide covers payments, products, subscriptions, tickets, and future modules. |
| App fee and ATM support share | App dashboard guide and Compliance boundaries describe fee ownership and platform responsibilities. |
| HTTP webhook URL | Webhooks and XRPC explains raw-body signatures, delivery ids, event filtering, retry, and redrive. |
| XRPC receiver URL | Service-auth cookbook and Webhooks and XRPC explain optional receiver callbacks and ATM service-auth verification. |
| Event subscriptions | Webhook events and Event payload examples list supported event types and payload contracts. |
| Send test event | Webhook test console and Testing package explain local receiver tests before real checkout. |
| Delivery logs and redrive | App dashboard guide and Testing cookbook explain failed/config-needed deliveries and safe replay. |
| Signing secret copy and rotation | App dashboard guide plus Security model cover current/previous secrets and rotation overlap. |
| Service-auth audience and methods | Authentication, Service-auth cookbook, and API reference document lxm/aud/iss expectations. |
| Tickets module and QR/pass settings | Tickets overview links to atmosphere.tickets for ticket-specific setup, holds, issuance, QR/pass, and scanner flows. |
App profile
The app profile uses the same ATM profile fields as any account: avatar, display name, and description. App-specific fields should be limited to app URL, modules, fees, receivers, and developer config.
- Use an app-owned DID, not a developer's personal DID.
- Set an app URL that users and operators can recognize.
- Keep payment processor ids, secrets, and webhook URLs private in ATM state.
Environments
| Test | Default for new apps. Use it for fake payments, app sandbox traffic, receiver testing, and module integration. |
|---|---|
| Live | Explicit production configuration with separate webhook URL, signing secret, event selection, and fee settings. |
| Environment switcher | Every app developer page should make the active environment obvious before saving config. |
Modules
Modules control which surfaces an app can use. Enabling a module does not make an app responsible for every user-facing feature; it grants the app access to the matching ATM contracts and dashboard tools.
| Payments | Hosted checkout, app-scoped payment visibility, receipts, refunds through ATM policy, and payment events. |
|---|---|
| Products | Catalog refs, app fulfillment links, product/update/archive events, and product purchase visibility. |
| Subscriptions | Recurring payment relationships, app subscription policy, amount changes, cancellation, and renewal events. |
| Tickets | Ticket availability, holds, free claims, issuance, QR/pass settings, verify, check-in, and ticket events. |
| Machine payments | Roadmap module for MPP/x402-style flows; keep disabled until the contract is tested. |
Fees
Independent apps receive the app fee they configure. ATM does not add a mandatory ATM fee on top. Apps may optionally share a portion of their app fee back to ATM.
- App fee
- The fee configured by the originating app for payments it starts.
- ATM support share
- Optional percentage of the app fee the app voluntarily shares with ATM.
- ATM-owned apps
- Apps such as Supper keep their app fee inside ATM because they share the same legal entity.
Webhooks
HTTP webhooks are the default receiver path. ATM signs every delivery with the environment-specific secret and stores attempts so developers can redrive safely.
- Verify the exact raw body before parsing JSON.
- Verify `Atm-Signature` and `Atm-Delivery-Id`.
- Store delivery id before side effects.
- Return success for duplicates after confirming state.
- Use the dashboard to send test events and redrive failed deliveries.
XRPC receivers
XRPC receivers are optional and useful for AT Protocol-native apps that already expose an app service. They receive the same event envelope, but authenticate ATM with service-auth instead of HMAC.
| Best for | Apps that already host XRPC methods and want protocol-shaped callbacks. |
|---|---|
| Not required for | Simple apps, webhook-only apps, or early starter-kit integrations. |
| Verify | Issuer, audience, method NSID, expiry, signature, and replay state. |
Delivery logs
Delivery logs are the operational truth for app callbacks. Use them when a buyer paid but the app UI did not update, or when a ticket issued but the event app did not display it.
- 01
Queued
ATM has stored the event and scheduled delivery.
- 02
Delivered
Receiver returned success; app should have processed idempotently.
- 03
Failed
Receiver returned error or timed out; fix endpoint then redrive.
- 04
Config needed
No receiver URL is configured yet; add one and redrive pending deliveries.
- 05
Filtered
The app disabled this event type for the environment.
Secrets and rotation
Rotate secrets per environment. During overlap, ATM can emit multiple v1 signatures so receivers accept either current or previous secret.
- Never paste webhook secrets into browser code.
- Rotate test and live secrets independently.
- Deploy receiver support for the new secret before ending overlap.
- Use the dashboard copy state to avoid copying stale values.
Moving to live
- Test environment passes checkout, callback, redrive, and refund paths.
- Live webhook or XRPC receiver is configured separately.
- Live app fee and ATM support share are reviewed.
- Recipient payability checks are implemented before payment buttons appear.
- Support, privacy, and terms links are ready.