Webhooks & Events

How event systems work on the JTL platform: ERP webhooks, AppBridge events, and the setup handshake.

The JTL platform has three 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

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: Publishing events from your app to the host is in active development. Subscribing to host entity-context events is available today.

What they are: Events exchanged between your Cloud App and the App Shell over the iframe messaging channel. Communication is asynchronous and non-blocking, so your app continues executing while the message is delivered, with no HTTP request or polling involved.

When to use them:

• Reacting when the merchant navigates to a different customer, order, quotation, or item
• Notifying the App Shell that your app completed an action (in development)

Subscribing to Host Events

A panel subscribes to host events to react when the merchant navigates to a different entity. Each ERP entity view publishes its own change event, using PascalCase past-tense names with object payloads.

const unsubscribe = appBridge.event.subscribe(
  "CustomerChanged",
  ({ customerId }) => {
    if (!customerId) return;

    // Load data for this customer.
  },
);

See Reading Panel Context for the full list of events and the pattern.

Publishing Events

Publishing will let your app notify the host when it completes an action, for example when a verification step finishes or a generated description is ready to insert. The API is in active development.

Key Characteristics

Property	Value
Direction	Host to your app today. App to host in development.
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 app 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 app 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.

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

---

What’s Next?

Handling Webhooks

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

Error Handling

Handle failures in event processing and API calls.