Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Mercaline2024/Ecomdrop-ia-connector-2/llms.txt

Use this file to discover all available pages before exploring further.

The Webhooks API handles incoming webhook events from Shopify. These endpoints are automatically called by Shopify when certain events occur.
These endpoints are designed to be called by Shopify only. Do not call them directly from your application.

​
Order Created Webhook

Triggered when a new order is created in Shopify. Sends order data to Ecomdrop for processing. 
POST /webhooks/orders/create

​
Webhook Topic

ORDERS_CREATE (GraphQL API webhook)

​
Payload

Shopify sends order data in GraphQL format. The webhook handler processes:

​
Processing Flow

  1. Configuration Check: Verifies Ecomdrop API key and Flow ID are configured
  2. Data Transformation: Converts GraphQL order data to Ecomdrop format
  3. Callback URL: Adds callback URL for status notifications
  4. Flow Trigger: Sends data to Ecomdrop flow for processing
  5. Tag Update: Adds error tag if immediate failure occurs

​
Response

OK
The webhook always returns 200 OK to prevent Shopify from retrying. Errors are logged but not returned to Shopify.

​
Ecomdrop Integration

When configured, the webhook:
  1. Transforms order data to Ecomdrop-compatible format
  2. Includes callback URL: {SHOPIFY_APP_URL}/api/ecomdrop/callback
  3. Sends API key in payload for callback authentication
  4. Triggers the configured “Nuevo Pedido” flow ID
  5. Waits for async callback to update order tags

​
Order Data Sent to Ecomdrop

{
  "orderId": "gid://shopify/Order/5678901234567890",
  "orderName": "#1001",
  "orderNumber": "1001",
  "createdAt": "2026-03-04T10:30:00Z",
  "totalPrice": "149.99",
  "currency": "USD",
  "financialStatus": "PAID",
  "fulfillmentStatus": "UNFULFILLED",
  "lineItems": [
    {
      "id": "gid://shopify/LineItem/123",
      "name": "Premium Product",
      "quantity": 2,
      "price": "74.99",
      "sku": "PROD-001",
      "variantId": "gid://shopify/ProductVariant/456",
      "productId": "gid://shopify/Product/789"
    }
  ],
  "customer": {
    "id": "gid://shopify/Customer/987654321",
    "email": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+1234567890"
  },
  "shippingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "province": "NY",
    "country": "United States",
    "zip": "10001",
    "phone": "+1234567890"
  },
  "shop": "mystore.myshopify.com",
  "eventType": "order_created",
  "callbackUrl": "https://your-app.com/api/ecomdrop/callback",
  "callbackApiKey": "ecomdrop_api_key"
}

​
Draft Order Created Webhook

Triggered when a draft order (abandoned cart) is created in Shopify. Sends data to Ecomdrop for abandoned cart recovery flows. 
POST /webhooks/draft_orders/create

​
Webhook Topic

DRAFT_ORDERS_CREATE (GraphQL API webhook)

​
Payload

Shopify sends draft order data in GraphQL format.

​
Processing Flow

  1. Configuration Check: Verifies “Carrito Abandonado” flow ID is configured
  2. Data Transformation: Converts draft order data to Ecomdrop format
  3. Flow Trigger: Sends to abandoned cart recovery flow

​
Response

OK

​
Draft Order Data Sent to Ecomdrop

{
  "draftOrderId": "gid://shopify/DraftOrder/1234567890",
  "draftOrderName": "#D1",
  "createdAt": "2026-03-04T10:30:00Z",
  "totalPrice": "99.99",
  "currencyCode": "USD",
  "lineItems": [
    {
      "id": "gid://shopify/DraftOrderLineItem/123",
      "title": "Product Name",
      "quantity": 1,
      "originalUnitPrice": "99.99",
      "sku": "SKU-001"
    }
  ],
  "customer": {
    "id": "gid://shopify/Customer/987",
    "email": "customer@example.com",
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "email": "customer@example.com",
  "shop": "mystore.myshopify.com",
  "eventType": "draft_order_created"
}

​
App Uninstalled Webhook

Triggered when the app is uninstalled from a Shopify store. Cleans up all store data. 
POST /webhooks/app/uninstalled

​
Webhook Topic

APP_UNINSTALLED

​
Processing Flow

  1. Session Cleanup: Deletes all sessions for the shop
  2. Configuration Cleanup: Removes shop configuration
  3. Product Associations: Deletes all product associations
  4. AI Configuration: Removes AI settings

​
Response

​
Data Cleaned Up

  • All session records
  • Shop configuration (Ecomdrop/Dropi settings)
  • Product associations
  • AI configuration
This webhook ensures GDPR compliance by removing all shop data when the app is uninstalled.

​
App Scopes Update Webhook

Triggered when the app’s permission scopes are updated in Shopify. 
POST /webhooks/app/scopes_update

​
Webhook Topic

APP_SCOPES_UPDATE

​
Payload

​
current
array
Array of current permission scopes granted to the app

​
Processing Flow

  1. Extract Scopes: Gets current scopes from payload
  2. Update Session: Updates the session record with new scopes

​
Response

​
Example Payload

{
  "current": [
    "read_products",
    "write_products",
    "read_orders",
    "write_orders",
    "read_customers"
  ]
}
This webhook ensures the app’s stored session data stays in sync with Shopify’s current permissions.

​
Webhook Configuration

To set up these webhooks in your Shopify app:

​
Required Webhooks

TopicEndpointPurpose
ORDERS_CREATE/webhooks/orders/createNew order processing
DRAFT_ORDERS_CREATE/webhooks/draft_orders/createAbandoned cart recovery
APP_UNINSTALLED/webhooks/app/uninstalledData cleanup
APP_SCOPES_UPDATE/webhooks/app/scopes_updatePermission sync

​
Webhook Format

All webhooks use GraphQL format (not REST/JSON) for better data structure and type safety.

​
Error Handling

All webhooks return 200 OK regardless of processing errors to prevent Shopify from retrying. Errors are logged internally for debugging.