Skip to main content
If you’re designing a payments backend from scratch around Sly, three architectural patterns cover 80% of what you’ll build. Pick the one(s) that fit; compose where needed.

Event-driven

Webhooks as the primary signal. Most integrations start here — it’s the simplest model that scales.

Queue-backed workers

Decouple webhook ack from processing. Essential once you’re past prototype or have heavy per-event work.

State-machine modeled

Model orders, checkouts, or agents as explicit FSMs. Best for regulated flows and complex multi-step commerce.

Agent-embedded

Agent runs inside your product with Ed25519 credentials + policy enforcement. See the Agent Platform section.

​
Decision tree

→ Event-driven. Single server, webhook handler, straight to database. Start here.
→ Add queue-backed workers. Ack the webhook in <200ms; process async. See queue-backed workers.
→ State-machine. Explicit transitions catch invalid operations and simplify reasoning about concurrency. See state-machine.
→ State-machine with audit log. Every transition is a durable event; your audit trail writes itself.
→ Queue-backed + batched database writes. Individual webhook-to-DB-insert doesn’t scale past ~500 events/sec. Queue, batch-write.
→ Agent-embedded. Ed25519 credentials, policy evaluation, approval workflows. See Agent Platform.
→ Compose patterns. Event-driven handler → queue for heavy events → state machines per business object. Each pattern operates on the layer above it.

​
Common themes across patterns

Regardless of which pattern you pick:
  • Every webhook handler is idempotent. Dedupe by X-Sly-Event-Id. At-least-once delivery means retries.
  • Every external write uses idempotency keys. POST /v1/transfers with a stable idempotency_key never double-executes.
  • Every multi-step operation has a failure path. If step 2 succeeds and step 3 fails, you need to either complete step 3 or roll back step 2 cleanly.
  • Every Sly response includes request_id. Log it. It’s how you and Sly support trace any issue end-to-end.

​
Anti-patterns to avoid

  • Synchronous chains — webhook → database → external API → another external API → response. Too fragile. Break with queues.
  • State in handlers — webhook handlers should be stateless; all state in the database or queue.
  • Logging the webhook secret — happens shockingly often. Scan your logs.
  • Skipping signature verification “in staging” — staging webhook endpoints get discovered and abused.
  • Global idempotency keys — use per-operation keys, not "1" incrementing. UUIDs are free.

​
Reference architectures

The next three pages show reference shapes: Each includes: recommended tech, webhook handler shape, error handling, and scaling notes.