Signing & Verification in the App System
Overview
To ensure secure communication between Shopware shops and your app server, Shopware signs all outgoing requests using a cryptographic signature. The signature is generated using HMAC-SHA256, hashing either the query string or the request body, depending on the request method, with your app secret. By verifying this signature on your server, you can confirm that the request originates from Shopware and remains unaltered during transmission. This mechanism safeguards your app against request forgery and unauthorized access.
WARNING
Breaking Change Considerations
Shopware may add parameters used for signature generation without considering it a breaking change. Your app should be flexible enough to handle variations in the signature generation data.
To simplify signature verification and response signing, use our App PHP SDK or the Symfony Bundle.
If you are not using these tools, ensure that you base signature generation on all query parameters or the entire request body, rather than selecting specific parameters.
Prerequisites
You should be familiar with the concept of Apps and their registration flow.
Your app server must be also accessible for the Shopware server. You can use a tunneling service like ngrok for development.
Validating requests
INFO
Query parsing of signature
Avoid re-parsing and re-encoding the query string for HMAC validation, as parameter order and URL encoding may vary depending on the programming language used.
Shopware signs all requests sent to your app server using a cryptographic signature. This signature is generated by hashing the request's query string with your app secret.
To ensure the request originates from Shopware, you should verify this signature before processing it.
Validating re-registration signatures
When a shop re-registers an app it already knows — to rotate the app secret, or after a shop-URL change — the registration request carries a second signature in addition to the normal one. Alongside the signature made with your app's secret, Shopware adds a signature made with the previous secret the app already holds. Your app must validate both before accepting the re-registration: the first proves the request is for your app, the second proves it comes from the shop that registered before.
Validate each signature with the same HMAC check used for a normal request, using the matching secret. For when this happens and how to roll the secret over without dropping in-flight requests, see Secret rotation and shop-url changes.
Signing responses
Shopware expects a signature in the response to verify that the response is coming from your app server.
