Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 30 ยท APIs

Apps, Webhooks and Signatures

Understand the Shopware app system: manifest.xml, the registration handshake, webhook events, HMAC signature checks, retries and idempotent handlers.

A plugin is PHP code that lives inside the shop. An app is the opposite: a separate web service, written in any language and hosted anywhere, that Shopware talks to over HTTP. The shop tells the app when something happens (a webhook), and the app calls the shop's Admin API when it wants to read or change data. Apps are how most extensions for Shopware's hosted offerings are built, and they are a good choice for any integration where you do not want to run code inside someone else's shop.

This lesson compares apps with plugins, walks through a manifest.xml, explains the registration handshake that sets up a shared secret, and shows how to verify a webhook with an HMAC signature. The manifest and HTTP exchanges are read-only, because there is no Shopware shop on this site. The runnable examples are PHP stand-ins that perform the same signing and verification with hash_hmac; the cryptography is real, the shop and app are simulated. The general ideas behind signed webhooks are covered in Webhooks and Signatures, and the API your app will call is in The Admin API and Integrations.

Apps versus plugins

Plugin App
Runs In the shop's PHP process As its own web service
Language PHP only Anything that speaks HTTP
Access to data Everything the code can reach (DAL, services, database) Only what its permissions allow, through the API
Can break the shop Yes, a bug can take down checkout Much less: a slow app delays only its own calls
Installation composer, plugin commands, needs file access Shopware reads a manifest and registers the app
Typical use Deep changes, custom entities, core behavior Integrations, extra admin pages, notifications

Neither is "better". If you need to decorate a core service or add a database table, you need a plugin. If you want to push orders to a CRM and run on your own infrastructure, an app is cleaner and safer for the shop owner. Some products combine both.

The manifest

An app is described by a manifest.xml in the app folder (read-only; add the schema reference line from the Shopware docs of your version):

XML
<manifest>
    <meta>
        <name>AcmeOrderSync</name>
        <label>Order Sync</label>
        <description>Sends new orders to the Acme CRM</description>
        <author>Acme GmbH</author>
        <copyright>(c) Acme GmbH</copyright>
        <version>1.0.0</version>
        <license>MIT</license>
    </meta>

    <setup>
        <registrationUrl>https://app.example.com/shopware/register</registrationUrl>
        <secret>replace-with-a-long-random-string</secret>
    </setup>

    <permissions>
        <read>order</read>
        <read>customer</read>
        <update>order</update>
    </permissions>

    <webhooks>
        <webhook name="orderPlaced"
                 url="https://app.example.com/shopware/hooks/order-placed"
                 event="checkout.order.placed"/>
    </webhooks>
</manifest>

What each block does:

  • <meta> gives the app its technical name (name, which must match the folder name), a label for the Administration and a version. Raising the version triggers an app update.
  • <setup> holds the registrationUrl, where Shopware sends the handshake request, and the secret used to sign that first request. The secret is only for the very first exchange; day-to-day traffic uses a different secret that the handshake creates for each shop.
  • <permissions> lists the entities the app may read, create, update or delete. Shopware creates an integration for the app with exactly those rights. An app that asks for more than it needs is a red flag for merchants.
  • <webhooks> subscribes URLs to events. An event such as checkout.order.placed carries order data only if the app has read permission for that entity.

An app is installed with bin/console app:install --activate AcmeOrderSync for local development, or through the Store for production shops.

The registration handshake

When an app is installed, the shop and the app must agree on a secret without exposing it. The handshake has three steps.

sequenceDiagram
    participant S as Shopware shop
    participant A as App server
    S->>A: GET registrationUrl?shop-id=..&shop-url=..&timestamp=..<br/>(signed with the manifest secret)
    A->>A: verify signature, create a shop secret
    A-->>S: proof, secret, confirmation_url
    S->>S: check proof
    S->>A: POST confirmation_url (apiKey, secretKey, shopId, shopUrl)<br/>(signed with the shop secret)
    A->>A: verify, store the shop's API credentials

The shop proves it knows the manifest secret, the app proves it does too and hands over a per-shop secret; then the shop sends its API credentials.

  1. Shop to app. Shopware sends a GET request to the registrationUrl with the query parameters shop-id, shop-url and timestamp. A header called shopware-app-signature holds the HMAC-SHA256 of the raw query string, keyed with the manifest secret. The app recomputes it and compares. A mismatch means the call did not come from a shop that knows the secret, so the app refuses.
  2. App to shop. The app answers with JSON: a proof (the HMAC-SHA256 of the shop id, shop URL and app name concatenated, keyed with the manifest secret), a freshly generated secret for this one shop, and a confirmation_url. Shopware verifies the proof, which shows the app really knows the manifest secret.
  3. Shop to app, again. Shopware POSTs the integration credentials (apiKey, secretKey) plus shopId and shopUrl to the confirmation_url. This request is signed with the new shop secret, in the shopware-shop-signature header. The app stores the credentials per shop, which is how it later gets tokens to call the Admin API.

An app can serve many shops, so it must store one secret and one set of credentials per shop id, and look them up on every incoming request.

A handshake stand-in

The next stand-in plays both sides in one script. It uses the real HMAC functions and the structure above. It is simplified in that the "network" is a function call, the app name and URLs are made up, and the secrets are fixed so that the output is stable (a real app generates a random secret per shop).

PHP Registration handshake with HMAC

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Webhook events

Webhooks are the main way an app learns what happens in a shop. Besides entity events such as product.written and business events such as checkout.order.placed, the shop can also notify an app of its own lifecycle events (app.installed, app.updated, app.deleted, app.activated, app.deactivated). The lifecycle events are useful for creating and removing your per-shop records.

A delivery is an HTTP POST with a JSON body of roughly this shape (read-only):

JSON
{
  "data": {
    "payload": { "order": { "id": "0188a1b2c3d44e5f8a9b0c1d2e3f4a5b", "orderNumber": "10042" } },
    "event": "checkout.order.placed"
  },
  "source": {
    "url": "https://shop.example.com",
    "appVersion": "1.0.0",
    "shopId": "shop-7f3a"
  },
  "timestamp": 1700000000
}

The exact payload depends on the event and the version; check what your shop sends before you rely on a field. The body is signed. The shop computes the HMAC-SHA256 of the raw request body with the shop secret from the handshake and puts it in the shopware-shop-signature header.

Verifying a webhook

Your endpoint must verify before it trusts anything:

  1. Find the shop by source.shopId (or a path parameter) and load its secret. Unknown shop: reject.
  2. Compute the HMAC-SHA256 over the raw body bytes exactly as received. Do not decode and re-encode the JSON first, because a single changed space gives a different hash.
  3. Compare with the header using a constant-time function (hash_equals in PHP). A plain === leaks timing information.
  4. Check the timestamp against a tolerance window, for example five minutes, to reject replayed old requests. The timestamp is inside the signed body, so it cannot be changed without breaking the signature.
  5. Only then act on the data, and answer quickly with a 2xx status.

Answer fast. Do slow work (CRM calls, emails) in your own queue, not inside the request. A webhook that times out counts as failed.

Retries and idempotency

Delivery is at least once. If your endpoint is down, times out or returns an error status, Shopware retries the delivery through its message queue a limited number of times and records failures in the shop. Retries can also produce duplicates when your server processed the request but the response was lost. Therefore your handler must be idempotent: handling the same event twice must have the same effect as once. The standard approach is a table of already-processed event keys. Check whether your Shopware version sends a unique event id; if not, build a key from stable fields such as the event name, the entity id and the timestamp. See Idempotency for the full pattern, and Scheduled Tasks and the Message Queue for how the shop side delivers work in the background.

Also expect events to arrive out of order. An order.updated may reach you before order.placed. Fetch the current state from the Admin API when order matters, instead of trusting the payload as the latest truth.

A webhook receiver stand-in

This stand-in signs a webhook the way the shop does and verifies it the way your endpoint should, including tamper detection, replay protection and duplicate suppression. The clock is fixed so the result is repeatable.

PHP Sign, verify and de-duplicate a webhook

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The stand-in does the cryptography with PHP's real hash_hmac and hash_equals; the shop, the request and the processed-keys table are simplified. In a production app the processed keys live in a database with a unique index, so two parallel deliveries cannot both pass the check.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. When should you choose a plugin over an app?

    Only plugins run inside the shop process and can change core behavior or the schema. Apps work through HTTP, webhooks and the Admin API.
  2. 2. What does the shopware-shop-signature header on a webhook contain?

    The shop signs the body with the per-shop secret from the handshake. The app recomputes the hash and compares it in constant time.
  3. 3. Why compare signatures with hash_equals instead of ===?

    A normal comparison can stop at the first different character, and that timing difference can help an attacker guess a signature.
  4. 4. Your webhook endpoint receives the same order.placed event twice. What should happen?

    Delivery is at least once. An idempotent handler records processed keys and treats repeats as already done.
  5. 5. Why must the signature be computed over the raw request body?

    The hash covers exact bytes. Whitespace or key order changes after decoding give a different result and a false rejection.

Summary

  • Plugins run inside the shop; apps are external HTTP services that use webhooks and the Admin API and are limited by declared permissions.
  • manifest.xml declares the app's metadata, registration URL, permissions and webhook subscriptions.
  • The registration handshake exchanges signed requests, a proof and a per-shop secret, and finally the shop's API credentials; store them per shop.
  • Verify every webhook: look up the shop secret, HMAC the raw body, compare with hash_equals, check the timestamp, then act.
  • Delivery is at least once and can be out of order, so deduplicate with a key and re-read current state when it matters.

Next, move to the shop front end with Storefront Templates with Twig.