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: Server-to-server callbacks defined in your app’s manifest.json. The JTL platform calls these URLs when specific lifecycle events occur; primarily when a merchant installs or uninstalls your app.How they work: You define URLs in the lifecycle section of your manifest. When the event occurs (e.g. a merchant installs your app), JTL sends a request to your URL. Your server processes it and responds.When to use them:
Setting up tenant-specific data when a merchant installs your app
Cleaning up data when a merchant uninstalls your app
Establishing the initial connection between your app and a merchant’s tenant
The setupUrl 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.
