Интеграция Shopify и n8n: заказы, webhooks и идемпотентность в CRM ¶

Обновлено: 2026-05-30

Проблема: Shopify webhook может приходить повторно, а order update похож на новый заказ. Если n8n без проверки сразу создаёт сделку или строку в складе, появляются финансовые и операционные дубли.

Решение: Нужно принимать Shopify webhook как критичное событие: проверить topic, shop domain и подпись, собрать idempotency key по order_id/topic, нормализовать customer/line_items и только потом обновлять CRM или склад.

Проблема: почему простая интеграция создаёт дубли и ручной хаос ¶

Интеграция Shopify и n8n обычно начинается с задачи “передать заказ в CRM”. Но у ecommerce-сценариев больше рисков: повторная доставка webhook, возвраты, частичные оплаты, изменение адреса, тестовые заказы и разные статусы fulfillment.

Если workflow не различает order created, order paid, fulfilled и cancelled, команда может дважды отгрузить товар, создать две сделки или отправить лишнее уведомление клиенту. Поэтому эта страница фокусируется на order webhook, idempotency и понятном контракте для downstream-систем.

Архитектура workflow для n8n ¶

Для ecommerce нельзя считать все Shopify events одинаковыми. Обработка order paid и fulfillment updated должна быть отдельной от order created, иначе бизнес-действия повторятся.

Контракт входных данных ¶

{
  "topic": "orders/paid",
  "shop_domain": "demo-store.myshopify.com",
  "id": 5812345678901,
  "name": "#10492",
  "email": "client@example.com",
  "created_at": "2026-05-30T10:00:00+03:00",
  "currency": "RUB",
  "financial_status": "paid",
  "fulfillment_status": null,
  "total_price": "12900.00",
  "customer": {
    "id": 998877,
    "first_name": "Иван",
    "last_name": "Петров",
    "phone": "+7 916 123-45-67"
  },
  "shipping_address": {
    "city": "Москва",
    "address1": "ул. Примерная, 10"
  },
  "line_items": [
    {
      "sku": "N8N-SETUP",
      "name": "Настройка интеграции",
      "quantity": 1,
      "price": "12900.00"
    }
  ]
}

В тестовом payload topic передан как поле для удобства. В production Shopify topic обычно приходит в headers, поэтому workflow должен читать и headers, и body.

Code Node: нормализация, mapping и guard-условия ¶

const src = $json.body ?? $json;
const headers = $json.headers ?? {};
const topic = String(headers['x-shopify-topic'] ?? src.topic ?? '').trim();
const shop = String(headers['x-shopify-shop-domain'] ?? src.shop_domain ?? '').trim().toLowerCase();
const allowedTopics = ['orders/create', 'orders/paid', 'orders/fulfilled', 'orders/cancelled'];
const allowedShops = ['demo-store.myshopify.com'];
if (!allowedTopics.includes(topic)) return [{ json: { action: 'ignore', reason: 'topic_not_allowed', topic } }];
if (!allowedShops.includes(shop)) throw new Error(`Shopify shop is not allowed: ${shop}`);
const orderId = String(src.id ?? src.admin_graphql_api_id ?? '').trim();
if (!orderId) throw new Error('No Shopify order id');
const lines = Array.isArray(src.line_items) ? src.line_items.map(item => ({
  sku: String(item.sku ?? '').trim(),
  name: String(item.name ?? '').trim(),
  quantity: Number(item.quantity ?? 0),
  price: Number(item.price ?? 0)
})) : [];
return [{ json: {
  action: 'sync_order',
  idempotency_key: `shopify:${shop}:${topic}:${orderId}`,
  shop,
  topic,
  order_id: orderId,
  order_name: String(src.name ?? '').trim(),
  customer_email: String(src.email ?? src.customer?.email ?? '').trim().toLowerCase(),
  customer_phone: String(src.customer?.phone ?? src.phone ?? '').trim(),
  total_price: Number(src.total_price ?? 0),
  currency: String(src.currency ?? '').trim(),
  financial_status: String(src.financial_status ?? '').trim(),
  fulfillment_status: src.fulfillment_status ?? 'not_fulfilled',
  line_items: lines,
  crm_comment: `Shopify ${topic} ${src.name ?? orderId}`
}}];

Готовый workflow JSON: скачать и импортировать ¶

Скачать готовый workflow JSON Скачать тестовый payload

{
  "name": "Nodbot - Shopify order webhook to CRM with idempotency",
  "nodes": [
    {
      "name": "Shopify Webhook",
      "type": "n8n-nodes-base.webhook",
      "purpose": "Принять order event"
    },
    {
      "name": "Validate Shopify event",
      "type": "n8n-nodes-base.code",
      "purpose": "Проверить topic/shop/signature"
    },
    {
      "name": "Normalize order",
      "type": "n8n-nodes-base.code",
      "purpose": "Собрать order contract"
    },
    {
      "name": "Check idempotency",
      "type": "n8n-nodes-base.postgres",
      "purpose": "Не обработать event дважды"
    },
    {
      "name": "Update CRM or ERP",
      "type": "n8n-nodes-base.httpRequest",
      "purpose": "Передать заказ"
    },
    {
      "name": "Respond",
      "type": "n8n-nodes-base.respondToWebhook",
      "purpose": "Вернуть 200"
    }
  ],
  "connections": "Shopify Webhook → Validate Shopify event → Normalize order → Check idempotency → Update CRM or ERP → Respond"
}

Пошаговая настройка связки ¶

1. Создайте Shopify webhook только для нужных order topics.
2. Включите проверку подписи или вынесите её в reverse proxy/Code Node.
3. Импортируйте workflow JSON и замените shop allowlist, credentials и CRM endpoint.
4. Определите отдельные правила для paid, fulfilled и cancelled.
5. Проверьте повторную доставку одного webhook и отмену заказа.

Тесты перед production ¶

curl -X POST "https://YOUR-N8N-DOMAIN/webhook/integration-shopify-n8n-order-webhook" \
  -H "Content-Type: application/json" \
  --data @integration-shopify-n8n-order-webhook-payload.json

1. Повторный payload не создаёт дубль и возвращает тот же output key.
2. Некорректный mapping останавливается до запроса к внешнему API.
3. Пустые необязательные поля не ломают workflow.
4. Ошибка API уходит в alert или DLQ с безопасным payload.
5. Execution data не содержит секретов, токенов и лишних персональных данных.

Production-риски ¶

• Нет проверки подписи. Публичный webhook URL можно подделать.
• Все topics идут в один create. Отмена или fulfillment создаёт новую сделку вместо обновления.
• Idempotency только по order_id. Разные события одного заказа блокируют друг друга.
• Line items превращены в текст. Склад или ERP не сможет обработать SKU и количество.
• Ответ webhook ждёт CRM слишком долго. Лучше быстро подтвердить событие и отправить тяжёлую обработку в очередь.

Полезные ссылки и смежные материалы ¶

• Shopify Webhooks overview
• Shopify webhook topics
• Creating webhooks in Shopify admin
• Webhook signature validation
• Webhook idempotency to Postgres

Критерии готовности ¶

1. Webhook topic, shop domain и signature проверяются до бизнес-логики.
2. Idempotency key включает shop, topic и order_id.
3. Line items сохраняют SKU, quantity и price структурно.
4. Paid, fulfilled и cancelled имеют разные правила обработки.
5. Ошибки CRM/ERP уходят в alert или DLQ без потери webhook.