Webhooks & Events

The JTL platform has four 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
ERP Webhooks	Signed HTTP push	Cloud Apps	Reacting to data changes in the merchant’s ERP: items, customers, orders, invoices, stock
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
Setup Handshake	iframe handshake	Cloud Apps	App installation: onboarding UI and the tenant connection
SCX Events	Polling (pull)	Marketplace Channels	Consuming seller actions: new offers, order updates, attribute changes

ERP Webhooks

What they are: Signed HTTP requests that JTL sends to your app when data changes in the merchant’s ERP. An item is edited, an order is paid, stock moves between warehouses, and your endpoint hears about it within seconds. How they work: You declare the topics you want and an HTTPS endpoint in your app manifest. When a matching change occurs, JTL posts a signed request to that endpoint. The payload carries the key of the entity that changed rather than the entity itself, so your handler verifies the signature, acknowledges the delivery, and then fetches the current record through the GraphQL API. When to use them:

Keeping your own store in sync with ERP data
Triggering work when an order reaches a status your app cares about
Reacting to stock movements, returns, or payment changes without polling

Manifest Configuration

Subscriptions live under capabilities.erp.webhooks in your app.json:

{
  "capabilities": {
    "erp": {
      "webhooks": {
        "apiVersion": "2023-04",
        "subscriptions": [
          {
            "topics": [
              "com.jtl.erp.workflow.v1.item.created",
              "com.jtl.erp.workflow.v1.item.changed"
            ],
            "endpoint": {
              "url": "https://app.yourcompany.com/webhooks/items"
            }
          }
        ]
      }
    }
  }
}

Each subscription pairs a set of topics with one endpoint, so different domains can route to different handlers.

Key Characteristics

Property	Value
Direction	One-way. JTL posts to your endpoint.
Delivery	At-least-once. Failed deliveries are retried.
Payload	Entity key and change metadata. Fetch the record through the GraphQL API.
Security	Every delivery is signed. Verify the signature before acting on it.
Scope	Per tenant, identified by `tenantid` in the payload
Availability	Cloud Apps with webhook subscriptions in their manifest

Treat an unverified delivery as untrusted input. Your endpoint is a public URL, and the signature is the only thing that distinguishes a real event from a forged one.

For the topic list and the handler implementation, see Webhook Topics and Handling Webhooks.

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

Setup Handshake

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 setup URL 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 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 data changes in the merchant’s ERP	ERP Webhooks
A Cloud App	React to user actions in real time	AppBridge Events
A Cloud App	Handle app install onboarding	Setup Handshake
A Marketplace Channel	Process seller actions (offers, orders, attributes)	SCX Events

What’s Next?

Handling Webhooks

Declare subscriptions, receive deliveries, and fetch the changed entity.

Marketplace Channels: Channel API

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

Error Handling

Handle failures in event processing and API calls.

Essentials

Cloud Apps

ERP Integration

Event Systems at a Glance

ERP Webhooks

Manifest Configuration

Key Characteristics

AppBridge Events

Key Characteristics

Setup Handshake

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?

Handling Webhooks

Marketplace Channels: Channel API

Error Handling

​Event Systems at a Glance

​ERP Webhooks

​Manifest Configuration

​Key Characteristics

​AppBridge Events

​Publish and Subscribe

​Key Characteristics

​Setup Handshake

​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?

Handling Webhooks

Marketplace Channels: Channel API

Error Handling

Event Systems at a Glance

ERP Webhooks

Manifest Configuration

Key Characteristics

AppBridge Events

Publish and Subscribe

Key Characteristics

Setup Handshake

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?