How event systems work on the JTL platform: AppBridge events, lifecycle hooks, and SCX polling events.
The JTL platform has three different event systems depending on what you’re building and what kind of events you need to handle. This guide explains each one, how they differ, and when to use which.
In development: AppBridge publish/subscribe events are in development and not yet available. This section will be updated when the API ships.
What they will be: Real-time, bidirectional events between your Cloud App and the App Shell. Your app can both publish events (tell the host something happened) and subscribe to events (react when the host tells you something happened).How they will work: AppBridge events use the iframe messaging channel. When your app publishes an event, the App Shell receives it instantly. When the App Shell publishes an event, your app’s subscriber callback fires immediately. Communication is asynchronous and non-blocking, so your app continues executing while the message is delivered (no HTTP request, polling, or delay).When to use them (planned):
Notifying the JTL App Shell that your app completed an action (e.g. order verification finished)
Reacting to user navigation or context changes in the JTL-Wawi
Coordinating between your app and other platform components
Publishing events: your app notifies the host that something happened (for example, a verification step completed or a generated description is ready to insert).
Subscribing to events: your app listens for events from the host and reacts when context changes (for example, the merchant navigates to a different record).
Topics will follow a resource:action naming convention (for example, order:verification:complete or inventory:updated) so the intent of an event is clear from its name alone.
What they are: A URL defined in your app’s manifest.json that JTL loads in an iframe when a merchant installs your app.How they work: You define a configurationUrl in the lifecycle section of your manifest. When a merchant installs your app, JTL loads that URL inside the JTL Hub. Your app shows its onboarding UI, completes the AppBridge handshake, and signals setup is done by calling appBridge.method.call('setupCompleted').When to use it:
Showing onboarding UI when a merchant installs your app
Verifying the session token from AppBridge and persisting the tenant connection
Collecting any configuration the merchant needs to provide
Display a setup screen inside the App Shell. Verify the session token from AppBridge, persist the tenant connection, and complete the handshake with appBridge.method.call('setupCompleted').
The configurationUrl is the most important lifecycle hook. It’s the entry point for the merchant’s first interaction with your app. If this URL is unreachable when a merchant tries to install your app, the installation fails. Make sure it’s always available.
For implementation details, see the Quick Start: From Scratch guide, which walks through the full setup handshake.
What they are: An event queue for marketplace channel integrations. When sellers (merchants using JTL) take actions like creating a new product offer, updating prices, or shipping an order, those actions are queued as events. Your channel integration polls the queue, processes the events, and acknowledges them.How they work: This is a pull-based system, not push-based. JTL doesn’t send events to your server. Instead, your app periodically calls GET /v1/channel/event to check for new events, processes them, and then calls DELETE /v1/channel/event to acknowledge them. Unacknowledged events are redelivered.When to use them:
Processing new product listings from sellers
Handling order status updates (paid, shipped, cancelled)
Always acknowledge events after successful processing. If you don’t acknowledge an event, it will be redelivered after a timeout — up to 10 times. After 10 delivery attempts, the event becomes a failed event and is permanently discarded.
