如何在Shopware 6 Cloud App中创建路由以注册至第三方平台Webhook

一、创建Webhook接收路由 #

1. 控制器实现（以PHP/Symfony为例） #

Shopware Cloud App基于Symfony框架，直接在src/Controller下创建处理Webhook的控制器：

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

class WebhookController extends AbstractController
{
    #[Route('/webhook/order-change', name: 'webhook_order_change', methods: ['POST'])]
    public function handleOrderChange(Request $request): Response
    {
        // 验证Shopware Webhook签名，防止恶意请求
        $signature = $request->headers->get('shopware-webhook-signature');
        $secret = $this->getParameter('shopware_webhook_secret');
        $payload = $request->getContent();
        
        if (!$this->verifySignature($payload, $signature, $secret)) {
            return new Response('无效签名', Response::HTTP_UNAUTHORIZED);
        }

        // 解析订单变更数据
        $orderData = json_decode($payload, true);
        
        // 执行业务处理逻辑
        $this->processOrderUpdate($orderData);

        return new Response('Webhook处理完成', Response::HTTP_OK);
    }

    private function verifySignature(string $payload, ?string $signature, string $secret): bool
    {
        if (!$signature) return false;
        $expectedHash = hash_hmac('sha256', $payload, $secret);
        return hash_equals($expectedHash, $signature);
    }

    private function processOrderUpdate(array $orderData): void
    {
        // 示例：提取订单ID与状态，对接第三方平台或内部系统
        $orderId = $orderData['data']['id'];
        $currentStatus = $orderData['data']['attributes']['stateMachineState']['name'];
        
        // 调用Shopware订单API获取完整订单信息（若需）
        $fullOrder = $this->getOrderDetails($orderId);
    }

    private function getOrderDetails(string $orderId): array
    {
        $apiClient = $this->get('shopware_api_client'); // 提前配置API客户端服务
        $response = $apiClient->request('GET', "/api/order/$orderId", [
            'headers' => [
                'Authorization' => 'Bearer ' . $this->getParameter('shopware_api_token'),
                'Content-Type' => 'application/json',
            ],
        ]);
        return json_decode($response->getContent(), true);
    }
}

2. 路由与权限配置 #

• 在config/routes.yaml中确认路由加载：

webhook_routes:
    resource: '../src/Controller/WebhookController.php'
    type: annotation

• 在Shopware Cloud后台的App配置页，将/webhook/order-change加入允许访问的路由列表，确保外部请求能到达。

二、注册Shopware Webhook #

1. 登录Shopware Cloud后台，进入设置 > Webhooks
2. 点击"添加Webhook"，配置核心参数：
   • 事件: 选择订单相关事件（如order.state.change、order.placed）
   • URL: 填入你的App的Webhook完整地址（例如https://your-app-domain.com/webhook/order-change）
   • 密钥: 设置加密密钥，需与代码中shopware_webhook_secret参数完全一致
   • 请求头: 保留默认签名头即可
3. 保存后，Shopware会自动发送测试请求验证路由有效性。

三、订单API对接注意事项 #

• 认证方式: 使用Shopware Cloud后台创建的集成Token（路径：设置 > 集成），需勾选订单相关的读写权限
• 幂等处理: 记录Webhook请求体中的meta.eventId，重复请求直接返回成功，避免重复处理
• 事件过滤: 通过请求体中的event字段区分不同订单变更类型，只处理业务需要的事件

四、常见问题排查 #

• 路由无法访问: 检查App防火墙配置，确保/webhook/*路径允许外部POST请求；确认Shopware Cloud App已配置正确的域名白名单
• 签名验证失败: 核对密钥是否一致，注意请求体在传输过程中未被修改（如中间件转码导致内容变化）
• API权限不足: 检查集成Token的权限范围，确保拥有订单数据的读写权限

内容的提问来源于stack exchange，提问作者Ayush