Webhooks & 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.

Event Systems at a Glance

System	Model	Used by	Use when
AppBridge Events	Real-time, bidirectional (push)	Cloud Apps	Communication between your app and the JTL App Shell like reacting to user actions and notifying the host of state changes
Lifecycle Hooks	iframe handshake	Cloud Apps	App installation: onboarding UI and the setup handshake
SCX Events	Polling (pull)	Marketplace Channels	Consuming seller actions: new offers, order updates, attribute changes

AppBridge Events

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

AppBridge events will support two capabilities:

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.

Key Characteristics

Property	Value
Direction	Bidirectional: your app ↔ App Shell
Delivery	Instant (through the iframe)
Scope	Only within the current user session. Events don’t persist or queue.
Availability	Cloud Apps running inside the App Shell only

Lifecycle Hooks

What they are: A URL defined in your app’s app.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

Manifest Configuration

The lifecycle hook is defined in your app.json:

{
  "lifecycle": {
    "configurationUrl": "https://app.yourcompany.com/setup"
  }
}

Hook	When it’s triggered	What to do
`configurationUrl`	Merchant initiates app installation	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')`.

Key Characteristics

Property	Value
Direction	One-way — JTL Hub loads your URL in an iframe
Delivery	Iframe render in the merchant’s browser
Scope	Per-tenant onboarding
Availability	Cloud Apps with a registered manifest

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.

SCX Events (Polling)

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)
Syncing attribute and category changes

Poll → Process → Acknowledge

Poll: Your app calls GET /v1/channel/event at regular intervals (recommended: every 60 seconds)
Process: Handle each event based on its type (new offer, order update, attribute change, etc.)
Acknowledge: Call DELETE /v1/channel/event with the IDs of events you’ve successfully processed

Event Structure

Each event in the eventList has this shape:

{
  "id": "63623b997d2c89a4e3e9f3c7",
  "type": "Seller:Offer.New",
  "createdAt": "2022-11-02T14:38:53+00:00",
  "event": {
    "sellerId": "1",
    "offerId": 822,
    "sku": "843609",
    "title": "Fahrrad Halterung",
    "quantity": "0",
    "taxPercent": "19",
    "priceList": [ ... ],
    "channelAttributeList": [ ... ]
  }
}

Field	Description
`id`	Unique event identifier — use this for acknowledgement
`type`	The event type (e.g. `Seller:Offer.New`, `Seller:Meta.SellerAttributesUpdateRequest`)
`createdAt`	When the event was created (ISO 8601)
`event`	The event payload that varies by event type

Acknowledging Events

After processing, acknowledge events by sending their IDs:

// DELETE /v1/channel/event
{
  "eventIdList": [
    "63623b997d2c89a4e3e9f3c7",
    "636280fd65a66c4430ec0d67"
  ]
}

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.

Key Characteristics

Property	Value
Direction	Pull: your app polls the SCX API
Delivery	Queued. Events wait until your app fetches them.
Reliability	Guaranteed delivery (up to 10 retries). Events persist until acknowledged or dead-lettered.
Ordering	Events are returned in creation order
Scope	Seller events for your connected channel
Availability	SCX Channel API (Marketplace Channels only)

Best Practices for SCX Event Polling

Practice	Why
Poll every ~60 seconds	Balances responsiveness with rate limit usage
Acknowledge in batches	Send all processed event IDs in a single DELETE call, not one per event
Process idempotently	Events can be redelivered if acknowledgement fails. Design handlers that produce the same result if called twice with the same event.
Handle unknown event types gracefully	New event types may be added. Log and acknowledge events your app doesn’t recognise rather than failing.
Monitor for dead letters	If events are dead-lettering, your processing pipeline has a problem that needs investigation.

Choosing the Right Event System

I’m building…	I need to…	Use
A Cloud App	React to user actions in real time	AppBridge Events
A Cloud App	Handle app install onboarding	Lifecycle Hooks
A Marketplace Channel	Process seller actions (offers, orders, attributes)	SCX Events

What’s Next?

Cloud Apps: Handling Webhooks

Implementation guide for AppBridge events and lifecycle hooks in Cloud Apps.

Marketplace Channels: Channel API

Full guide to building a marketplace channel integration, including SCX event handling.

Rate Limiting

Manage your API usage when polling for events at regular intervals.

Error Handling

Handle failures in event processing and API calls.

Essentials

Cloud Apps

Marketplace Channels

ERP Integration

Vouchers API

Event Systems at a Glance

AppBridge Events

Key Characteristics

Lifecycle Hooks

Manifest Configuration

Key Characteristics

SCX Events (Polling)

Poll → Process → Acknowledge

Event Structure

Acknowledging Events

Key Characteristics

Best Practices for SCX Event Polling

Choosing the Right Event System

What’s Next?

Cloud Apps: Handling Webhooks

Marketplace Channels: Channel API

Rate Limiting

Error Handling

​Event Systems at a Glance

​AppBridge Events

​Publish and Subscribe

​Key Characteristics

​Lifecycle Hooks

​Manifest Configuration

​Key Characteristics

​SCX Events (Polling)

​Poll → Process → Acknowledge

​Event Structure

​Acknowledging Events

​Key Characteristics

​Best Practices for SCX Event Polling

​Choosing the Right Event System

​What’s Next?

Cloud Apps: Handling Webhooks

Marketplace Channels: Channel API

Rate Limiting

Error Handling

Event Systems at a Glance

AppBridge Events

Publish and Subscribe

Key Characteristics

Lifecycle Hooks

Manifest Configuration

Key Characteristics

SCX Events (Polling)

Poll → Process → Acknowledge

Event Structure

Acknowledging Events

Key Characteristics

Best Practices for SCX Event Polling

Choosing the Right Event System

What’s Next?