Webhooks - Ecomdrop IA Connector

Overview

Webhooks enable real-time communication between Shopify and the Ecomdrop IA Connector. When specific events occur in your Shopify store, webhooks automatically notify the app, which then triggers configured Ecomdrop flows.

Webhook Types

The app registers and handles four webhook topics:

1. Orders Created (ORDERS_CREATE)

Purpose: Triggers when a new order is placed in your store Endpoint: /webhooks/orders/create Trigger Condition: Customer completes checkout and order is created Source File: app/routes/webhooks.orders.create.tsx

Event Flow

Customer completes purchase in Shopify
Shopify sends ORDERS_CREATE webhook (GraphQL format)
App validates store configuration
If nuevoPedidoFlowId is configured, app formats order data
App calls Ecomdrop API to trigger the assigned flow
Returns 200 OK to Shopify (prevents retries)

2. Draft Orders Created (DRAFT_ORDERS_CREATE)

Purpose: Triggers when a draft order is created (abandoned cart scenario) Endpoint: /webhooks/draft_orders/create Trigger Condition: Draft order created manually or via checkout abandonment Source File: app/routes/webhooks.draft_orders.create.tsx

Event Flow

Draft order is created in Shopify
Shopify sends DRAFT_ORDERS_CREATE webhook
App retrieves store configuration
If carritoAbandonadoFlowId is configured, app processes draft order
App triggers Ecomdrop abandoned cart flow
Returns 200 OK to Shopify

Draft order webhooks fire for ALL draft orders, not just abandoned carts. Ensure your flow logic accounts for this.

3. App Uninstalled (APP_UNINSTALLED)

Purpose: Cleanup when merchant uninstalls the app Endpoint: /webhooks/app/uninstalled Source File: app/routes/webhooks.app.uninstalled.tsx

Cleanup Process

The webhook handler deletes all store data:

Sessions (db.session.deleteMany)
Shop Configuration (db.shopConfiguration.deleteMany)
Product Associations (db.productAssociation.deleteMany)
AI Configuration (db.aIConfiguration.deleteMany)

This ensures GDPR compliance and prevents orphaned data.

4. App Scopes Updated (APP_SCOPES_UPDATE)

Purpose: Updates session when app permissions change Endpoint: /webhooks/app/scopes_update Source File: app/routes/webhooks.app.scopes_update.tsx

Update Process

When Shopify notifies of scope changes:

Webhook receives new scopes in payload.current

App updates session in database:

await db.session.update({
  where: { id: session.id },
  data: { scope: current.toString() }
});

Returns 200 OK

Webhook Security

Shopify webhooks use HMAC signatures to verify authenticity.

Authentication Flow

Shopify Signs Request

Shopify generates HMAC-SHA256 signature using your app’s client secret

App Validates Signature

The authenticate.webhook(request) method verifies:

HMAC signature in headers
Request origin from Shopify
Timestamp freshness (prevents replay attacks)

Process or Reject

Valid webhooks are processed; invalid ones are rejected with 401

The Shopify App Bridge handles webhook authentication automatically. You don’t need to implement manual verification.

Security Best Practices

Always Verify HMAC

Never process webhook data without validating the HMAC signature. This prevents malicious requests from triggering flows.

Return 200 for All Requests

Always return HTTP 200, even on errors. This prevents Shopify from retrying failed webhooks indefinitely.

try {
  // Process webhook
} catch (error) {
  console.error(error);
  return new Response("OK", { status: 200 }); // Still return 200
}

Secure API Keys

Store Ecomdrop API keys encrypted in the database. Never log them in plaintext.

Validate Payload Structure

Check that required fields exist before accessing them:

const order = (payload as any).order || payload;
if (!order || !order.id) {
  console.error("Invalid order payload");
  return new Response("OK", { status: 200 });
}

Webhook Payload Examples

Orders Create Payload

{
  "order": {
    "id": "gid://shopify/Order/5123456789012",
    "name": "#1001",
    "createdAt": "2024-01-15T10:30:00Z",
    "totalPriceSet": {
      "shopMoney": {
        "amount": "149.99",
        "currencyCode": "USD"
      }
    },
    "customer": {
      "id": "gid://shopify/Customer/4123456789012",
      "email": "customer@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+1234567890"
    },
    "lineItems": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/LineItem/123",
            "title": "Product Name",
            "quantity": 2,
            "originalUnitPrice": {
              "amount": "74.99"
            },
            "variant": {
              "id": "gid://shopify/ProductVariant/456",
              "sku": "PROD-001"
            }
          }
        }
      ]
    },
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "address1": "123 Main St",
      "city": "New York",
      "province": "NY",
      "country": "United States",
      "zip": "10001",
      "phone": "+1234567890"
    }
  }
}

Draft Orders Create Payload

{
  "draftOrder": {
    "id": "gid://shopify/DraftOrder/789",
    "name": "#D1",
    "createdAt": "2024-01-15T11:00:00Z",
    "totalPrice": {
      "amount": "199.99"
    },
    "currencyCode": "USD",
    "customer": {
      "id": "gid://shopify/Customer/456",
      "email": "customer@example.com",
      "firstName": "Jane",
      "lastName": "Smith"
    },
    "lineItems": {
      "edges": [
        {
          "node": {
            "title": "Another Product",
            "quantity": 1,
            "originalUnitPrice": {
              "amount": "199.99"
            }
          }
        }
      ]
    },
    "email": "customer@example.com"
  }
}

Webhook Processing

Data Transformation

The app transforms Shopify’s GraphQL webhook format into a simplified structure for Ecomdrop:

Extract Core Fields

Maps order ID, name, timestamps, and financial data

Format Customer Data

Extracts customer email, name, phone, and purchase history

Parse Line Items

Transforms nested GraphQL edges into flat array:

lineItems: order.lineItems?.edges?.map((edge: any) => {
  const item = edge.node;
  return {
    id: item.id,
    title: item.title,
    quantity: item.quantity,
    price: item.originalUnitPrice?.amount,
    sku: item.variant?.sku
  };
})

Add Metadata

Includes shop domain, event type, and callback URLs

Error Handling

Configuration Missing

If no API key or flow ID is configured:

if (!configuration?.ecomdropApiKey) {
  console.log(`⚠️ No API Key configured for ${shop}`);
  return new Response("OK", { status: 200 });
}

App logs warning and returns 200 (no error for Shopify).

API Call Failure

If Ecomdrop API call fails:

if (!result.success) {
  console.error(`❌ Failed to trigger flow: ${result.error}`);
  // Tag order with 'ecomdrop-error' for tracking
  await updateOrderTags({
    session,
    orderId: order.id,
    tags: ["ecomdrop-error"]
  });
}

Order is tagged for manual review.

Malformed Payload

If webhook payload is invalid:

try {
  const order = (payload as any).order || payload;
  // Process order
} catch (error) {
  console.error(`❌ Error processing webhook:`, error);
  return new Response("OK", { status: 200 });
}

Logs error and returns 200 to prevent retries.

Testing Webhooks

Using Shopify CLI

Start Development Server

npm run dev

Trigger Test Webhook

shopify app webhook trigger --topic ORDERS_CREATE

Review Logs

Check console output for webhook processing:

📦 Received ORDERS_CREATE webhook for shop.myshopify.com
🔍 Looking for configuration with shop: shop.myshopify.com

CLI test webhooks use a generic shop domain (shop.myshopify.com). Your configuration must exist for this test domain, or webhook will skip processing.

Testing in Production

Create Real Order

Place a test order in your Shopify store using Bogus Gateway

Monitor Webhook Delivery

In Shopify Admin:

Go to Settings > Notifications > Webhooks
Click on the webhook subscription
View delivery history and response codes

Check App Logs

Review your app’s server logs for processing details

Verify in Ecomdrop

Confirm the flow was triggered in your Ecomdrop panel

Manual Webhook Replay

You can replay failed webhooks from Shopify Admin:

Go to Settings > Notifications > Webhooks
Click the failed webhook subscription
Find the failed delivery
Click “Resend” to replay the webhook

Useful for testing fixes after resolving configuration issues.

Webhook Lifecycle

Troubleshooting

Webhooks Not Firing

Symptoms: No webhook logs when creating ordersSolutions:

Verify webhooks are registered in Shopify Admin > Settings > Notifications
Check webhook subscriptions in app configuration
Ensure app is deployed and publicly accessible
Review Shopify webhook delivery logs for errors
Confirm the app has required API scopes

Webhooks Received But Not Processing

Symptoms: Logs show webhook received but flow doesn’t triggerSolutions:

Check that Ecomdrop API key is configured
Verify flow ID is assigned for the event type
Review logs for configuration lookup failures
Ensure shop domain matches configuration record
Test Ecomdrop API connectivity manually

Duplicate Webhook Deliveries

Symptoms: Flow triggers multiple times for single orderSolutions:

Check Shopify webhook history for duplicates
Verify app isn’t deployed multiple times
Ensure webhook handler is idempotent
Review Ecomdrop for duplicate flow executions
Check for webhook replay actions in Shopify

Webhook Payload Errors

Symptoms: App logs show missing or malformed dataSolutions:

Log full payload to inspect structure
Verify GraphQL vs REST format expectations
Check Shopify API version compatibility
Handle optional fields with safe navigation (?.)
Add validation for required fields

Monitoring Webhooks

Key Metrics to Track

Delivery Success Rate

Monitor percentage of webhooks returning 200 OK

Processing Time

Track latency from webhook receipt to Ecomdrop API call

Flow Trigger Rate

Compare webhooks received vs flows actually triggered

Error Tags

Count orders tagged with ecomdrop-error

Logging Best Practices

The app uses structured logging with emojis for easy filtering:

📦 - Order webhook received
📝 - Draft order webhook received
🔍 - Configuration lookup
✅ - Success
❌ - Error
⚠️ - Warning
🚀 - Flow trigger

Search logs using these emojis to quickly find relevant events.

API Reference

Webhook Endpoints

Endpoint	Method	Topic	Purpose
`/webhooks/orders/create`	POST	ORDERS_CREATE	New order processing
`/webhooks/draft_orders/create`	POST	DRAFT_ORDERS_CREATE	Abandoned cart flow
`/webhooks/app/uninstalled`	POST	APP_UNINSTALLED	Data cleanup
`/webhooks/app/scopes_update`	POST	APP_SCOPES_UPDATE	Permission sync

Webhook Authentication

All webhooks must include Shopify HMAC headers:

X-Shopify-Hmac-Sha256: <signature>
X-Shopify-Shop-Domain: <shop>
X-Shopify-Topic: <topic>
X-Shopify-API-Version: <version>

Overview

Getting Started

Core Features

Integrations

Configuration

Deployment

Documentation Index

​Overview

​Webhook Types

​1. Orders Created (ORDERS_CREATE)

​2. Draft Orders Created (DRAFT_ORDERS_CREATE)

​3. App Uninstalled (APP_UNINSTALLED)

​4. App Scopes Updated (APP_SCOPES_UPDATE)

​Webhook Security

​Authentication Flow

​Security Best Practices

​Webhook Payload Examples

​Orders Create Payload

​Draft Orders Create Payload

​Webhook Processing

​Data Transformation

​Error Handling

​Testing Webhooks

​Using Shopify CLI

​Testing in Production

​Manual Webhook Replay

​Webhook Lifecycle

​Troubleshooting

​Monitoring Webhooks

​Key Metrics to Track

Delivery Success Rate

Processing Time

Flow Trigger Rate

Error Tags

​Logging Best Practices

​API Reference

​Webhook Endpoints

​Webhook Authentication

​Next Steps

Store Settings

Flow Management

Overview

Webhook Types

1. Orders Created (ORDERS_CREATE)

2. Draft Orders Created (DRAFT_ORDERS_CREATE)

3. App Uninstalled (APP_UNINSTALLED)

4. App Scopes Updated (APP_SCOPES_UPDATE)

Webhook Security

Authentication Flow

Security Best Practices

Webhook Payload Examples

Orders Create Payload

Draft Orders Create Payload

Webhook Processing

Data Transformation

Error Handling

Testing Webhooks

Using Shopify CLI

Testing in Production

Manual Webhook Replay

Webhook Lifecycle

Troubleshooting

Monitoring Webhooks

Key Metrics to Track

Logging Best Practices

API Reference

Webhook Endpoints

Webhook Authentication

Next Steps