apps
folder inside the custom
folder of your Shopware dev installation. In there, create another folder for your application and provide a manifest file in it.--no-validate
flag.--activate
flag to the app:install
command or by executing the app:activate
command after installation.shop-id
: The unique identifier of the shop the app was installed |shop-url
: The URL of the shop, this can later be used to access the Shopware API |timestamp
: The Unix timestamp when the request was created |shopware-app-signature
: The signature of the query stringsw-version
: The Shopware version of the shop (since 6.4.1.0)shopware-app-signature
header will be provided, which contains a cryptographic signature of the query string.
The secret used to generate this signature is the app secret
, that is unique per app and will be provided by the Shopware Account if you upload your app to the store. This secret won't leave the Shopware Account, so it won't be even leaked to the shops installing your app.app-secret
, therefore make sure you never accidentally publish your app-secret
.<secret>
in the manifest file, that is used for signing the registration request. However, if an app uses a hard-coded secret in the manifest it can not be uploaded to the store.<secret>
if you have an external app server.app secret
.app secret
you need to provide a proof that is signed with the app secret
too. The proof consist of the sha256 hmac of the concatenated shopId
, shopUrl
and your app's name.shopId
, shopUrl
and generated secret, so you can associate and use this information later.shop-secret
to distinguish it from the app-secret
. The app-secret
is unique for your app and is used to sign the registration request of every shop that installs your app. The shop-secret
will be provided by your app during the registration and should be unique for every shopconfirmation_url
of the registration with the following parameters send in the request body:apiKey
: The API key used to authenticate against the Shopware Admin APIsecretKey
: The secret key used to authenticate against the Shopware Admin APItimestamp
: The Unix timestamp when the request was createdshopUrl
: The URL of the shopshopId
: The unique identifier of the shopshopSecret
: The secret for the shop generated by the app and used for signing requestsshopId
. You can use the apiKey
and the secretKey
as client_id
and client_secret
respectively when you request an OAuth token from the Admin API.sw-version
header. Starting from Shopware version 6.4.5.0, the current language id of the Shopware context will be sent as a sw-context-language
header , and the locale of the user or locale of the context language is available under the sw-user-language
header.shop-secret
, that your app provided in the registration response and the signature can be found in the shopware-shop-signature
header.
You need to recalculate that signature and check that it matches the provided one, to make sure that the request is really send from shop with that shopId.read
, create
, update
, delete
) and the entity. Since version 6.4.12.0 your app can also request additional non-CRUD privileges with the <permission>
element.<webhooks>
element in your manifest file, like this:product-changed
and the url https://example.com/event/product-changed
which will be triggered if the event product.written
is fired. So every time a product is changed, your custom logic will get executed. Further down you will find a list of the most important events you can hook into.source
property contains all necessary information about the Shopware instance that send the request:url
is the url under which your app can reach the Shopware instance and its apiappVersion
is the version of the app that is installedshopId
is the id by which you can identify the Shopware instanceeventId
is a unique identifier of the event, this id will not change if sending of the webhook is retried, etc. Since 6.4.11.0.data
contains the name of the event so that a single endpoint can handle several different events, should you desire. data
also contains the event data in the payload
property, due to the asynchronous nature of theses webhooks the payload
for entity.written
events does not contain complete entities as these might become outdated. Instead the entity in the payload is characterized by its id, stored under primaryKey
, so that the app can fetch additional data through the shops API. This also has the advantage of giving the app explicit control over the associations that get fetched instead of relying on the associations determined by the event. Other events in contrast contain the entity data that defines the event, but keep in mind that event might not contain all associations.timestamp
is the time which the webhook was handled. This can be used to prevent replay attacks, as an attacker cannot change the timestamp without making the signature invalid. If the timestamp is too old, your app should reject the request. This property is only available from 6.4.1.0 onwardssw-version
header. Starting from Shopware version 6.4.5.0, the current language id of the shopware context will be sent as a sw-context-language
header , and the locale of the user or locale of the context language is available under the sw-user-language
header.shopware-shop-signature
every request should have a sha256 hmac of the request body, that is signed with the secret your app assigned the shop during the registration. The mechanism to verify the request is exactly the same as the one used for the confirmation request.api/notification
endpoint with a valid body and the header Authorization
token. Your app can request 10 times before being delayed by the system.status
property, the content of the notification as message
property and you can restrict users who can read the notification by passing requiredPrivileges
property and adminOnly
property inside the payload. When adminOnly
is true, only admins can read this notification. If you don't send the adminOnly
or adminOnly
is false, you can pass the requiredPrivileges
property so that users with specific permissions can read the notification. Otherwise, it will be displayed to every user.status
: Notification status, one of success
, error
, info
, warning
message
: The content of the notificationadminOnly
: Only admins can read this notification if this value is truerequiredPrivileges
: The required privileges that users need to have to read the notificationnotification:create
permission to access this api.app.installed
app.updated
app.deleted
app.activated
app.deactivated
app:validate
command to validate the configuration of your app. It will check for common errors, like:custom/apps
folder run:APP_URL
environment variable will be set to the correct URL to the shop. Especially it is assumed that the environment variable will be changed, when a shop is migrated to a new domain, or a staging shop is created as a duplicate of a production shop.bin/console app:url-change:resolve
command, or with a modal that pops up when the administration is opened.