---
title: Connecting the App and the App Server | Shopware Community Hub
description: >-
  Understand the Shopware App handshake process in detail: how to register your
  App Server, exchange secrets, and establish secure two-way communication.
canonical_url: 'https://hub.shopware.com/learn/unit/connecting-app-and-app-server'
---

# Connecting the App and the App Server

<LearningObjectives>

- **Establish** secure communication between an **App** and an **App Server** through the **Shopware handshake process**.
- **Describe** the **registration**, **proof/secret exchange**, and **confirmation steps** of the handshake.
- **Differentiate** between **JWT-signed incoming** and **OAuth-authenticated outgoing** requests.

</LearningObjectives>

# Connecting the App and the App Server

To exchange data between your App (Shopware) and your App Server, you need to establish a secure connection. This is done through a **handshake process**, which ensures that both sides know who they are talking to and that communication is secure and verifiable.

## The Handshake Process

The **handshake** occurs when the App is first activated in Shopware. It establishes the initial trust and securely shares secrets between the App and the App Server.

Below, you will see an overview of what happens in the background step by step:

### Step 1: Shopware Sends a Registration Request

When the App is activated, the handshake process is initiated. Shopware calls the `<registrationUrl>` of the App Server. This URL is defined in the `manifest.xml` file. The request is a **GET request** and contains important information such as the `shopId`, the `shopUrl`, and the `timestamp` in a **JSON body**.

For example:

```json
{
  "shopId": "X3IuJYEmIOQ3QsJ6",
  "shopUrl": "http://localhost:8000",
  "timestamp": 1735235800
}
```

When you activate your App, you can see the process looking at Symfony Server logs. It can be like this:

> `[Web Server ] Dec 26 17:56:40 |INFO   | SERVER GET  (200) /app/lifecycle/register?shop-id=X3IuJYEmIOQ3QsJ6&shop-url=http://localhost:8000&timestamp=1735235800 ip="::1"`

<Callout title="Further Reading" type="info">

For more details, see the [registration request documentation](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide.html#registration-request).

</Callout>

### Step 2: The App Server Responds with Proof and Secret

The App Server answers with a **registration response**, containing:

- A **proof** of the App's identity: A Hash from the **shop-id**, **shop-url** and your **App name**
- A **secret** to be used for future requests: A randomly generated string
- A **confirmation URL**: A URL Shopware sends the final confirmation

Here is an example server log:

> `[Web Server ] Dec 26 17:56:40 |INFO   | SERVER POST (204) /app/lifecycle/register-confirm host="127.0.0.1:8004" ip="::1" scheme="https"`

For more details, see the [registration response documentation](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide.html#registration-response).

### Step 3: Shopware Sends a Confirmation Request

Finally, Shopware sends a **POST request** to the `confirmation_url` provided by your App Server. This confirms that the App is successfully registered and can now communicate securely.

Here is an example server log:

> [Web Server ] Dec 26 17:56:40 |INFO   | SERVER POST (204) /app/lifecycle/register-confirm host="127.0.0.1:8004" ip="::1" scheme="https")

The confirmation request will provide a payload with parameters that the App Server can use to authenticate with the Shopware API.

### Communication Types

Once connected:

- Requests **from Shopware** to the **App Server** are signed with a [JWT token](https://developer.shopware.com/docs/guides/plugins/apps/clientside-to-app-backend.html).
- Requests **from the App Server** to the **Shopware** are [authenticated with an OAuth](https://github.com/shopware/app-php-sdk/blob/main/src/HttpClient/AuthenticatedClient.php) token.

<Callout title="Can One App Server Handle Multiple Apps?" type="info">

Normally, the relationship between a Shopware App and an App Server is defined as `1:1` - one Shopware App connects to one App Server.

Technically, it is possible to let one App Server handle **multiple Apps or multiple Shopware shops**. However, this requires more advanced setup and is **not part of this beginner course**.

</Callout>

### Common Pitfalls

During the handshake process, there are a few common pitfalls that can occur:

- The `registationUrl` in the `manifest.xml` file points to a **non-reachable** host.
- The `confirmationUrl` uses **HTTP instead of HTTPS** (Shopware requires HTTPS).
- The **server clock differs too much**, and therefore the timestamp verification fails.
- The required parameters are **missing** in the request.
- The App Server does not return a valid **proof**, and therefore Shopware rejects the connection.

Such things can be critical when your project becomes more complex, and therefore the maintainability takes more effort.

## Summary

In this learning unit, you learned how the **handshake process** establishes a secure connection between Shopware and your App Server. You now understand:

- How Shopware sends a **registration request** to your App Server
- How the App Server responds with a **proof**, **secret** and **confirmation URL**
- How Shopware finalizes the connection by sending a **confirmation request**
- How secure communication works using **JWT** (Shopware -> App Server) and **OAuth** (App Server -> Shopware)

**Congratulations!** You have completed the first course of this learning path. You now have a complete understanding of how Shopware Apps work – from setup to configuration to secure communication with an App Server.