All Tutorials

Manage webhook events with AWS EventBridge

All Tutorials

Manage webhook events with AWS EventBridge

Manage webhook events with AWS EventBridge

You can use Amazon EventBridge to receive webhook events from a shop. Tracking traffic from Shopify's platform can be overwhelming, especially as you grow your app. EventBridge's server-less, event-driven architecture can help you reduce infrastructure costs while providing a highly scalable system. This means you can spend less time managing servers and more time working on your apps.

This tutorial is divided into 4 parts:

  1. Set up an event source in Shopify's Partner Dashboard. This tells Shopify to send events to Amazon Web Services (AWS).
  2. Associate your event source with an event bus in the AWS Console.
  3. Create a rule for the event bus. This tells AWS what to do with the events received from the event bus. You can route events to SQS, Lambda, or another similar service.
  4. Create webhook subscriptions for EventBridge

Requirements

Before you start the tutorial, complete the folowing tasks:

  • Set up your Lambda function, SQS queue, or other EventBridge destination.
  • Copy your 12-digit AWS Account Id from the AWS console:
    1. Sign into the AWS Console.
    2. Click your name, then click My Account.
    3. Copy your 12-digit Account Id.

Integrate your app with EventBridge

1. Set up an event source in your Partner Dashboard

  1. In your Partner Dashboard, go to Apps and click the name of your app.
  2. Click App setup.
  3. In the Event Subscriptions section, under Amazon EventBridge, click Create source.
  4. Paste your AWS account ID, and choose your AWS region. The AWS region must match the region you select in the next part of the tutorial when you configure your event bus.
  5. Enter an event source name. All of your event sources must have unique names, so if you have multiple apps, consider a name that matches your app.
  6. Click Create to save your event source.

2. Associate your event source with an event bus in the AWS Console

After you set up an event source to deliver Shopify events to AWS, you need to configure an event bus to handle those events.

  1. In the AWS EventBridge console, navigate to Partner event sources page.
  2. In the Region drop-down, select the region you chose when you set up your event source.
  3. Click the event source you created in part 1. Make note of the ARN found under "Partner event source ARN". This will be the address you use later to create webhook subscriptions.
  4. Click Associate with event bus.
  5. On the next page, click Associate.

3. Create a rule for the event bus

After you've set up your event source and associated it with an event bus, you need to create a rule that tells AWS what to do with events it receives on the event bus.

  1. In the AWS console navigation menu, click Rules.
  2. In the drop-down, select your event bus.
  3. Click Create rule.
  4. Enter a rule name.
  5. Optional: Enter a description for the rule.
  6. In the Define pattern section, choose Event pattern, and select Pre-defined pattern by service. Alternatively, refer to Rule-based processing for custom filtering options.
  7. In the list of providers, choose All Events.
  8. In the Service name drop-down, select Shopify. This makes sure that only events sent by Shopify will be processed by this rule.
  9. In the Select event bus section, select the event bus that will use this rule.
  10. In the Select targets section, choose a Lambda function or SQS queue. Events processed by this rule will be sent to the function or queue that you select.
  11. Click Create.

EventBridge will now group and sort the events that your event source sends based on the rule you defined. You can define multiple rules by repeating the steps in part 3 of this tutorial.

You are now ready to create webhook subscriptions for EventBridge.

4. Create Webhook subscriptions for EventBridge

Lastly, you’ll create webhook subscriptions using the Partner event source ARN copied from step 2. You can retrieve this in the AWS console by navigating to Amazon EventBridge > Events > Partner event sources and then clicking on the Partner event source that you plan on using. Make sure you have copied the ARN of the Partner event source, and not the Event bus. Data sent via webhooks is divided by topic. Consult the Admin API reference for the complete list of supported webhook topics.

Subscriptions can be created when your app is installed on a shop and the oAuth flow completes.

Subscribing with GraphQL

EventBridge introduces new mutations for subscribing, updating and deleting.

Create a new webhook subscription using the eventBridgeWebhookSubscriptionCreate mutation

mutation {
  eventBridgeWebhookSubscriptionCreate(
    topic: PRODUCTS_CREATE
    webhookSubscription: {
      arn: <ARN-copied-from-step-2>
      format: JSON

  })
  {
    webhookSubscription {
      id
    }
    userErrors {
      message
    }
  }
}

Query for both HTTP and EventBridge subscriptions

{
  webhookSubscriptions(first: 10) {
    edges {
      node {
        id
        callbackUrl
        endpoint {
          __typename

          ... on WebhookHttpEndpoint {
            callbackUrl
          }
          ... on WebhookEventBridgeEndpoint {
            arn
          }
        }
      }
    }
  }
}

Subscribing with the REST API

Create a new webhook subscription using your event source ARN

Subscribing with the REST API is similar to subscribing to HTTP webhooks, but an ARN is specified as the address.

POST https://{shop_id}.myshopify.com/admin/api/2020-07/webhooks.json

{
"webhook": {
    "topic": "products/update",
    "address": <ARN-copied-from-step-2>,
    "format": "json"
  }
}

EventBridge payloads

The following is an example payload from EventBridge:

{
    "version": "0",
    "id": "1b8e2e75-b771-e964-f0e6-fbca6a21dad8",
    "detail-type": "shopifyWebhook",
    "source": "aws.partner/shopify.com/shop-event-bus",
    "account": "123456789",
    "resources": [""],
    "time": "2020-02-07T12:47:58Z",
    "region": "ca-central-1",
    "detail": {
        "payload": {
            "product" : {
                "id": 1,
                "title": "Columbia Las Hermosas",
                "body_html": "",
                "vendor": "Reunion Island",
                "product_type": "Coffee",
                "created_at": "2020-01-24T14:55:00-05:00",
                "handle": "columbia-las-hermosas",
                .
                .
                .
            }
        },
        "metadata": {
          "X-Shopify-Topic": "products/update",
          "X-Shopify-API-Version": "2020-01",
          "X-Shopify-HMAC": "rncNozYG6CCjmFJjEgUWowYJ60X+oUtsqul1sTwJMpU=",
          "X-Shopify-Shop-Domain": "reunioncoffeeroasters.myshopify.io",
          "X-Shopify-Order-Id": 1
       }
    }
}

You can use the information in EventBridge payloads to create custom rules in EventBridge.

Large payloads

Occasionally, a shop might have very large resources. If a Shopify resource would result in a payload larger than 255KB, then a special payload will be sent with the following error message:

{
    "version": "0",
    "id": "1b8e2e75-b771-e964-f0e6-fbca6a21dad8",
    "detail-type": "shopifyWebhook",
    "resources": [""],
    "source": "aws.partner/shopify.com/shop-event-bus",
    "account": "123456789",
    "time": "2020-02-07T12:47:58Z",
    "region": "ca-central-1",
    "detail": {
        "payload": {},
        "errors": [{"code": "payload_too_large", "message": "The payload is larger than the supported limit. Use the API to retrieve your data."}],
        "metadata": {
          "X-Shopify-Topic": "products/update",
          "X-Shopify-API-Version": "2020-01",
          "X-Shopify-HMAC": "rncNozYG6CCjmFJjEgUWowYJ60X+oUtsqul1sTwJMpU=",
          "X-Shopify-Shop-Domain": "reunioncoffeeroasters.myshopify.io",
          "X-Shopify-Product-Id": 1
       }
    }
}

You can use the resource ID in the X-Shopify-Order-Id field to request the resource using the REST or GraphQL Admin APIs.

Rule-based processing

You can choose to process events separately depending on, for example, which shop generated the event, or which resource triggered the event. Follow part 3 of this tutorial to create a rule for your event bus, but instead of choosing a pre-defined pattern, use the following steps to define a custom pattern for your rule.

Steps:

  1. When creating a rule, select Event pattern in the Define pattern section and then select Custom pattern.
  2. Enter a custom pattern that matches the structure of an EventBridge payload and click Save.

Event patterns in EventBridge rules have the same structure as the payloads that they match. The matching values are added to an array and compared using OR logic. You can also match by prefix using the prefix key. For more information, refer to Event Patterns in the Amazon documentation.

Custom event pattern examples

To match a specific shop domain, use the following pattern after you change the example domain to your store's domain:

{
    "detail-type": "shopifyWebhook",
    "detail": {
        "metadata": {
            "X-Shopify-Shop-Domain": ["reunioncoffeeroasters.myshopify.io"]
        }
    }
}

To match all products events, use the following pattern:

{
    "detail-type": "shopifyWebhook",
    "detail": {
        "metadata": {
            "X-Shopify-Topic": [{
                "prefix": "products"
            }]
        }
    }
}

Monitoring events and rules in EventBridge

As your app audience grows, your traffic can increase significantly. Consider using AWS CloudWatch to monitor your EventBridge integration for usage patterns and errors. For example, you can trigger an alert if an EventBridge rule is broken.