Consuming events

You react to the event stream in one of two ways. Both subscribe by topic and both receive the same event envelope; the difference is where your code runs.

Option 1 — handle events inside an App

If the reaction is part of a commerce app you're building, subscribe inside the app. You declare the topics in the manifest and the platform invokes your handler when one of them is published. Nothing leaves the platform, so there's no endpoint to host and no signature to check.

Declare the subscription in manifest.json:

{
  "events": {
    "listens": ["inventory.stock_changed", "pricing.updated"]
  }
}

Then handle each event in your app's code. See the App manifest reference for the events and policies blocks, and Apps for the runtime model. Use this when the reaction is part of the platform's own behavior — recompute a derived value, update a record, kick off another app's flow.

Option 2 — receive events at your own endpoint

If the reaction lives in your own infrastructure — an ERP, a data warehouse, a notification service — register a Webhook. You give the platform an HTTPS URL and a list of topics, and it POSTs each matching event to you as JSON, signed.

Because the request crosses the public internet, you must verify the signature on every delivery before trusting the body. The full scheme and a verification sample are in Webhook security.

# events arrive as POST <your-url> with the event envelope as the JSON body
def handle(request):
    verify_signature(request)          # see Webhook security — do this first
    event = request.json
    if already_processed(event["id"]):  # at-least-once: dedupe on event id
        return 200
    process(event["topic"], event["data"])
    return 200                          # 2xx tells the platform to stop retrying

Make handlers idempotent

Events are delivered at least once, so the same event can arrive twice — after a retry, or a network hiccup that dropped your acknowledgement. Both paths above can see a duplicate.

Key off the event id, which is stable across redeliveries of the same event. Record the ids you've handled and skip one you've seen before. Acknowledge fast: return success as soon as you've safely recorded the event, and do slow work afterward, so a delivery isn't retried just because your processing was slow.

When an event isn't the right tool

Events are fire-and-forget reactions to something that already happened. They're the wrong choice when:

• You need an answer now — call the API directly instead.
• The reaction must run a durable, multi-step process against an external system — use an Integration Studio workflow, which adds persistence and retries around the whole flow.

Where to go next

• Webhooks — register an endpoint and choose topics.
• Webhook security — verify a delivery's signature.
• Event types — the topics and payloads you can subscribe to.