From c8265bffdeffd43b9acab8d91ed5806066213138 Mon Sep 17 00:00:00 2001 From: Traci Porter Date: Thu, 17 Apr 2025 15:31:11 -0500 Subject: [PATCH 1/4] CSS-884:[update] moving webhook beta doc --- docs/integrations/webhooks/overview.mdx | 123 +++++++++++++++++++----- 1 file changed, 98 insertions(+), 25 deletions(-) diff --git a/docs/integrations/webhooks/overview.mdx b/docs/integrations/webhooks/overview.mdx index a3af734b7..7a1745c15 100644 --- a/docs/integrations/webhooks/overview.mdx +++ b/docs/integrations/webhooks/overview.mdx @@ -8,6 +8,14 @@ Webhooks notify applications when specific events occur on a BigCommerce store. This article is an overview of webhook behavior on BigCommerce. For webhook API reference, see [API Reference > Webhooks](/docs/webhooks/webhooks/manage-webhooks-bulk#create-a-webhook). For webhook event reference, see [Webhook Events](/docs/integrations/webhooks/events). For a step-by-step tutorial on creating webhooks for certain store events, see [Webhooks Tutorial](/docs/integrations/webhooks/tutorial). +## Supported webhook delivery types + +BigCommerce offers webhook delivery for the following endpoint types: + +* HTTPS +* Google Cloud Pub/Sub +* Amazon EventBridge + ## Creating a webhook To create a webhook, send a `POST` request to the [Create a webhook](/docs/webhooks/webhooks/manage-webhooks-bulk#create-a-webhooks) endpoint. Set the `scope` property value equal to the **Name / Scope** of the webhook you want to create. @@ -177,47 +185,31 @@ Accept: application/json } ``` -BigCommerce will send the specified headers when making callback requests to the destination server - this allows webhook destination URIs to be secured with basic authentication. +BigCommerce will send the specified headers when making callback requests to the destination server - this allows webhook destination URIs to be secured with basic authentication. The `hash` field is a SHA1 hash of event metadata, intended only to uniquely identify the event that triggered the webhook dispatch. If a hook fires twice for the same event, both request bodies should have the same hash. ## Troubleshooting -**Not receiving webhook event callbacks** - -If your app does not return an `HTTP 200` to BigCommerce after receiving the webhook event payload, BigCommerce considers it a failure. BigCommerce will keep trying for a little over 48 hours. At the end of that time, BigCommerce sends an email to the email address set during app registration and disables the webhook by setting the `is_active` flag to false. + -To see if a webhook is still active, send a request to the [Get a webhook](/docs/webhooks/webhooks/manage-webhooks-single#get-a-webhook) endpoint and check the value of the `is_active` property in the response. - -If you receive an email, or discover `is_active` is `false`, try the following: -* Verify the app is responding to the callback with a `200` response. -* Verify the destination server has a valid TLS/SSL setup by visiting `https://globalsign.ssllabs.com/`. Any of the following will cause the TLS/SSL handshake to fail: - * Self-signed certificates - * Hostname on certificate doesn't match the hostname in DNS settings - * Key and trust stores are not configured with the required intermediate certificates - -Once the issue is resolved, set `is_active` to `true` using the [Update a webhook](/docs/webhooks/webhooks/manage-webhooks-single#update-a-webhook) endpoint, so that BigCommerce starts sending event callback requests again. + **No 200 response from the [Create a webhook](/docs/webhooks/webhooks/manage-webhooks-bulk#create-a-webhook) endpoint** + * Check TLS/SSL configuration on the computer sending the request. -* Verify `POST` request contains the following required `HTTP` headers: +* Check the scope of the [event](/docs/integrations/webhooks/events) you’re subscribing to is correct -```http filename="Example request with required headers: Create a webhook" -POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/hooks -Accept: application/json -Content-Type: application/json -X-Auth-Token: {{ACCESS_TOKEN}} -``` **Unable to view your webhook** Webhooks created with one token are not visible when you retrieve webhooks using a different token. To view your webhook, use the same account token that created the webhook. -**Webhooks timing out** - -To prevent your webhooks from timing out, send a `200` success status response immediately after receiving the request. - **What are duplicate events?** In our event-based system, events are like messages that trigger actions within the system. Sometimes, for various reasons, these events can be received or processed more than once, causing "duplicate events." +**Duplicate webhook events** + +Duplicate webhooks can happen. For this reason, apps should use idempotent operations to avoid significant unintended side effects. Idempotent operations allow multiple calls without changing the result. A way to ensure webhook events are idempotent is to create a temporary "blacklist" array to store the hash of webhooks that have already been received or handled. When you receive a webhook, you can compare the hash of the received event to the list. If the hash has already been handled, you can ignore the event. + **Why do duplicate events happen?** Duplicate events can occur for several reasons: @@ -230,6 +222,87 @@ Duplicate events can occur for several reasons: BigCommerce recommends that apps use idempotent operations to prevent unintended side effects. Idempotent operations allow multiple calls without changing the result. One approach to ensuring webhook events maintain idempotence is by creating a temporary 'blocklist' array to store the hashes of webhooks that have already been received or handled. When you receive a webhook, you can compare the hash of the received event to the list. If the hash has already been handled you can ignore the event. + + + + +**Webhooks timing out** + +To prevent your webhooks from timing out, send a `200` success status response immediately after receiving the request. + +**Not receiving webhook event callbacks** + +If your app does not return an `HTTP 200` to BigCommerce after receiving the webhook event payload, BigCommerce considers it a failure. BigCommerce will keep trying for a little over 48 hours. At the end of that time, BigCommerce sends an email to the email address set during app registration and disables it by setting it as inactive. + +To see if a webhook is still active, send a request to the [Get a webhook](/docs/webhooks/webhooks/manage-webhooks-single#get-a-webhook) endpoint and check the value of the active property in the response. You can also retrieve your webhooks' active/inactive status in the store’s control panel. See [Viewing Webhooks](https://support.bigcommerce.com/s/article/Store-API-Accounts?language=en_US#webhooks). + +If you receive an email, or discover that your webhook is inactive, try the following: +* Verify the app responds to the callback with a `200` response. +* Verify the destination server has a valid TLS/SSL setup by visiting `https://globalsign.ssllabs.com/`. Any of the following will cause the TLS/SSL handshake to fail: + * Self-signed certificates + * Hostname on the certificate doesn't match the hostname in the DNS settings + * Key and trust stores are not configured with the required intermediate certificates + +Once the issue is resolved, set the webhook to active using the [Update a webhook](/docs/webhooks/webhooks/manage-webhooks-single#update-a-webhook) endpoint so that BigCommerce starts sending event callback requests again. + + + + +## Scenarios +**Webhook creation errors**. Possible causes of webhook creation errors are: +* The [topic](#topic-does-not-exist) doesn't exist. +* [Publisher permission](#publisher-permission-not-granted) isn't granted. +* There is an [internal service error](#internal-service-error). + +**Webhook update errors**. Possible causes of webhook update errors are: +* The [topic](#topic-does-not-exist) doesn't exist. +* [Publisher permission](#publisher-permission-not-granted) isn't granted. +* There is an [internal service error](#internal-service-error). + +**Webhook not received**. The possible causes why a webhook is not received are: +* Check that you created a webhook subscription on the correct event and triggered the event correctly. +* We deactivate the webhook if the topic was deleted or publisher permissions removed. You can check the webhook status. +* The Webhook delivery could have been delayed because of a spike in user activity or an incident. + + +## Errors + +### Topic does not exist + +This error occurs when the topic defined in the destination fields does not exist.

+**Error message**: `_Google topic '{{TOPIC_NAME}}' doesn't exist_`

+**How to fix**: Most probable, users have a typo in the defined topic or haven’t created it yet. + +### Publisher permission not granted + +This error occurs when the topic exists, but we (BigCommerce platform) don't have permission to publish it.

+**Error message**: `_Publisher permissions not granted for '{{TOPIC_NAME}}'_`

+**How to fix**: Users need to give our service account permission to publish. If a user has already done it and the error still happens, please double-check that you permitted the correct account or contact support with screenshots showing you granted permission successfully. + + +### Internal service error + +Something goes wrong on the BigCommerce side.

+**Error message**: All unexpected error messages should be treated as internal errors.

+**How to fix**: Retry your request after some time. If it doesn’t work, please get in touch with support. + + + + +**Field validation errors** + +To prevent and resolve a validation error, update the specific field to the proper value. + + +**Internal validation errors** + +The client should make another attempt with some delay to resolve an internal error. + + + + + + ## Tools From 06e58a03aac6b8ab746fd47b6e2e9518466ff87e Mon Sep 17 00:00:00 2001 From: Traci Porter Date: Thu, 17 Apr 2025 15:35:45 -0500 Subject: [PATCH 2/4] Create postman-collection.mdx --- .../webhooks/postman-collection.mdx | 455 ++++++++++++++++++ 1 file changed, 455 insertions(+) create mode 100644 docs/integrations/webhooks/postman-collection.mdx diff --git a/docs/integrations/webhooks/postman-collection.mdx b/docs/integrations/webhooks/postman-collection.mdx new file mode 100644 index 000000000..56308e2a0 --- /dev/null +++ b/docs/integrations/webhooks/postman-collection.mdx @@ -0,0 +1,455 @@ +# Webhooks Postman Collection + +One way to get started or refine requests is to use the BigCommerce Webhooks Postman collection, which contains core mutations and queries. To work with the Postman collection, you need to supply the following: + +* The sandbox store's `store_hash`. +* The sandbox store's `access_token`, which is available in one of the following ways: + * For store-level API accounts, the access token is created automatically when you create the API account. To learn more, see [Store-level API credentials](/docs/start/authentication/api-accounts#store-level-api-credentials) in our Guide to API Accounts. + * For app-level API accounts, a store-specific access token is available in your app's database as soon as you successfully install the app. You can also add a console log to get it from the terminal after the app completes the [auth callback](/docs/integrations/apps/guide/auth). For more about app-level API account, see [App-level API accounts](/docs/start/authentication/api-accounts#app-level-api-accounts) in our Guide to API Accounts. + +## Importing the collection + +The following code block is an exported Postman collection of Webhooks mutations and queries. To copy the collection, hover over the upper right corner of the code block and click the **Copy** icon that appears. + +For instructions on importing collections into Postman, see their article on [Importing and Exporting Data (Postman)](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#importing-postman-data). + +```json filename="Webhooks Postman collection" showLineNumbers copy +{ + "info": { + "_postman_id": "8eb8f3f2-529f-48cd-ab36-4fecd6fb3203", + "name": "Demo Starter | GraphQL Admin API - Webhooks", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", + "_exporter_id": "18324300" + }, + "item": [ + { + "name": "Create a GCP webhook", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "X-Auth-Token", + "value": "{{token}}" + }, + { + "key": "Accept-Encoding", + "value": "application/gzip", + "type": "text" + } + ], + "body": { + "mode": "graphql", + "graphql": { + "query": "mutation CreatePubSubWebhook($input:CreatePubSubWebhookInput!) {\n webhook {\n createPubSubWebhook(input: $input) {\n webhook {\n id\n scope\n destination\n status\n createdAt\n }\n }\n }\n}", + "variables": "{\n \"input\": {\n \t\"scope\": \"store/customer/created\",\n \t\"destination\": \"projects/gcp-pubsub-webhooks-demo/topics/bc-demo~store_customer_created\"\n }\n}" + } + }, + "url": { + "raw": "https://api.bigcommerce.com/stores/{{store_hash}}/graphql", + "protocol": "https", + "host": [ + "api", + "bigcommerce", + "com" + ], + "path": [ + "stores", + "{{store_hash}}", + "graphql" + ], + "query": [ + { + "key": "Accept-Encoding", + "value": "gzip", + "disabled": true + } + ] + } + }, + "response": [ + { + "name": "Create a GCP webhook", + "originalRequest": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "X-Auth-Token", + "value": "{{token}}" + }, + { + "key": "Accept-Encoding", + "value": "application/gzip", + "type": "text" + } + ], + "body": { + "mode": "graphql" + }, + "url": { + "raw": "https://api.bigcommerce.com/stores/{{store_hash}}/graphql", + "protocol": "https", + "host": [ + "api", + "bigcommerce", + "com" + ], + "path": [ + "stores", + "{{store_hash}}", + "graphql" + ], + "query": [ + { + "key": "Accept-Encoding", + "value": "gzip", + "disabled": true + } + ] + } + }, + "status": "OK", + "code": 200, + "_postman_previewlanguage": "json", + "header": [ + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "Transfer-Encoding", + "value": "chunked" + }, + { + "key": "Connection", + "value": "keep-alive" + }, + { + "key": "Vary", + "value": "Accept-Encoding" + }, + { + "key": "x-rate-limit-requests-left", + "value": "16101494" + }, + { + "key": "x-rate-limit-time-reset-ms", + "value": "29998" + }, + { + "key": "x-rate-limit-requests-quota", + "value": "16101495" + }, + { + "key": "x-rate-limit-time-window-ms", + "value": "30000" + }, + { + "key": "X-Request-ID", + "value": "9dc4b62d5d12d996648944a4205a49ab" + }, + { + "key": "Strict-Transport-Security", + "value": "max-age=31536000; includeSubDomains" + } + ], + "cookie": [], + "body": "{\n \"data\": {\n \"webhook\": {\n \"createGcpPubSubWebhook\": {\n \"webhook\": {\n \"id\": \"bc/store/webhook/26066947\",\n \"scope\": \"store/customer/*\",\n \"destination\": \"projects/gcp-pubsub-webhooks-demo/topics/bc-demo~store_customer_created\",\n \"isActive\": true,\n \"createdAt\": \"2023-04-13T20:01:37Z\",\n \"attributes\": []\n }\n }\n }\n }\n}" + } + ] + }, + { + "name": "Create a HTTP webhook", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "X-Auth-Token", + "value": "{{token}}" + }, + { + "key": "Accept-Encoding", + "value": "application/gzip", + "type": "text" + } + ], + "body": { + "mode": "graphql", + "graphql": { + "query": "mutation CreateHTTPWebhook($input:CreateHttpsWebhookInput!) {\n webhook {\n createHttpsWebhook(input: $input) {\n webhook {\n destination\n status\n id\n scope\n createdAt\n headers {\n key\n value\n }\n \n }\n }\n}\n}", + "variables": "{\n \"input\": {\n \"scope\": \"store/order/updated\",\n \t\"destination\": \"https://webhook.site/607d5ab5-6475-4ee8-9bb4-30b490436f49\",\n \"headers\": [\n {\n \"key\": \"My-Custom-Header\",\n \"value\": \"My custom header value\"\n }\n ]\n }\n \n}" + } + }, + "url": { + "raw": "https://api.bigcommerce.com/stores/{{store_hash}}/graphql", + "protocol": "https", + "host": [ + "api", + "bigcommerce", + "com" + ], + "path": [ + "stores", + "{{store_hash}}", + "graphql" + ], + "query": [ + { + "key": "Accept-Encoding", + "value": "gzip", + "disabled": true + } + ] + } + }, + "response": [] + }, + { + "name": "Get All Webhooks", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "X-Auth-Token", + "value": "{{token}}" + }, + { + "key": "Accept-Encoding", + "value": "application/gzip", + "type": "text" + } + ], + "body": { + "mode": "graphql", + "graphql": { + "query": "query getAllHooks($cursor: String) {\n \n store {\n webhooks (first: 50, after: $cursor) {\n pageInfo {\n startCursor\n endCursor\n hasNextPage\n }\n edges {\n cursor\n node {\n id\n scope\n status\n ... on HttpsWebhook {\n destination\n }\n ... on PubSubWebhook {\n destination\n }\n createdAt\n updatedAt\n }\n }\n }\n }\n}", + "variables": "" + } + }, + "url": { + "raw": "https://api.bigcommerce.com/stores/{{store_hash}}/graphql", + "protocol": "https", + "host": [ + "api", + "bigcommerce", + "com" + ], + "path": [ + "stores", + "{{store_hash}}", + "graphql" + ], + "query": [ + { + "key": "Accept-Encoding", + "value": "gzip", + "disabled": true + } + ] + } + }, + "response": [] + }, + { + "name": "Update GCP webhook: Deactivate the webhook", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "X-Auth-Token", + "value": "{{token}}" + }, + { + "key": "Accept-Encoding", + "value": "application/gzip", + "type": "text" + } + ], + "body": { + "mode": "graphql", + "graphql": { + "query": "mutation UpdateWebhook($input:UpdatePubSubWebhookInput!) {\n webhook {\n updatePubSubWebhook(input: $input) {\n webhook {\n id\n status\n }\n }\n }\n}", + "variables": "{\n \"input\": {\n \"data\": {\n \"isActive\": false\n },\n \"id\": \"bc/store/webhook/27069041\"\n }\n}" + } + }, + "url": { + "raw": "https://api.bigcommerce.com/stores/{{store_hash}}/graphql", + "protocol": "https", + "host": [ + "api", + "bigcommerce", + "com" + ], + "path": [ + "stores", + "{{store_hash}}", + "graphql" + ], + "query": [ + { + "key": "Accept-Encoding", + "value": "gzip", + "disabled": true + } + ] + } + }, + "response": [] + }, + { + "name": "Delete Webhook", + "event": [ + { + "listen": "test", + "script": { + "exec": [ + "" + ], + "type": "text/javascript" + } + } + ], + "request": { + "method": "POST", + "header": [ + { + "key": "Accept", + "value": "application/json" + }, + { + "key": "Content-Type", + "value": "application/json" + }, + { + "key": "X-Auth-Token", + "value": "{{token}}" + }, + { + "key": "Accept-Encoding", + "value": "application/gzip", + "type": "text" + } + ], + "body": { + "mode": "graphql", + "graphql": { + "query": "mutation DeleteWebhook {\n webhook {\n deleteWebhook(id: \"bc/store/webhook/25765861\") {\n id\n }\n }\n}", + "variables": "" + } + }, + "url": { + "raw": "https://api.bigcommerce.com/stores/{{store_hash}}/graphql", + "protocol": "https", + "host": [ + "api", + "bigcommerce", + "com" + ], + "path": [ + "stores", + "{{store_hash}}", + "graphql" + ], + "query": [ + { + "key": "Accept-Encoding", + "value": "gzip", + "disabled": true + } + ] + } + }, + "response": [] + } + ] +} +``` + +## Resources + +* [Guide to API Accounts](/docs/start/authentication/api-accounts) +* [Apps Guide: Implementing OAuth](/docs/integrations/apps/guide/auth) +* [Importing and Exporting Data (postman.com)](https://learning.postman.com/docs/getting-started/importing-and-exporting-data/#importing-postman-data) From f29c26c3faf2c5781102402816c88fdcf04300af Mon Sep 17 00:00:00 2001 From: Traci Porter Date: Fri, 25 Apr 2025 09:28:57 -0500 Subject: [PATCH 3/4] Create aws-webhooks-overview.mdx --- .../webhooks/aws-webhooks-overview.mdx | 224 ++++++++++++++++++ 1 file changed, 224 insertions(+) create mode 100644 docs/integrations/webhooks/aws-webhooks-overview.mdx diff --git a/docs/integrations/webhooks/aws-webhooks-overview.mdx b/docs/integrations/webhooks/aws-webhooks-overview.mdx new file mode 100644 index 000000000..6971d5a78 --- /dev/null +++ b/docs/integrations/webhooks/aws-webhooks-overview.mdx @@ -0,0 +1,224 @@ +# Amazon Webhooks Overview + +Amazon EventBridge is a serverless event bus that distributes events to connect application components and build highly scalable and resilient event-driven applications. It offers a simple way to consume webhook events from the BigCommerce platform at scale. + +To use Amazon EventBridge, you must do the following: +* [Set up an event source](#set-up-an-event-source-not-available-in-beta) +* [Associate your event source with an event bus](#associate-an-event-bus-not-available-in-beta) +* [Create rules for the event bus](#create-a-rule-not-available-in-beta) +* Subscribe to webhooks + +## Prerequisites +- To try out GraphQL queries and view responses, import our API examples into [Postman](https://www.getpostman.com/) or any other tool that allows testing of GraphQL queries. +- Enter the following environment variables before starting: + +| Credentials | Variables | +|:-------------------|:------------------------| +| Store variables | zone | +| | store_hash | +| OAuth credentials | client_id | + + + +## Set up an event source + +Setting up an event source with EventBridge allows you to send event data to Amazon services directly instead of being responsible for receiving that traffic yourself through a front-end web server. You can set up an event source using a Create AWS Event Source query. + + + +```graphql filename="Example query: Create Amazon Event Source" showLineNumbers copy +POST https://{{zone}}/stores/{{store_hash}}/graphql +mutation createEventSource($input: CreateEventSourceInput!){ + webhook { + createEventSource(input: $input) { + eventSource { + id + awsAccount + arn + eventSourceName + eventSourceRegion + } + } + } +} +``` + +```graphql filename="GraphQL variables" showLineNumbers copy +{ + "input" : { + "awsAccount": "649666292244", + "eventSourceName": "Final-Test-1", + "eventSourceRegion": "US_EAST_1", + "clientId": "4yk6pb824t53hirbuz5akdr652lpjb2" + } +} +``` + + +```graphql filename="Example response: Create Amazon Event Source" showLineNumbers copy +{ + "data":{ + "webhook": { + "createEventSource": { + "eventSource": { + "id": "bc/store/eventSource/9", + "awsAccount": "932486483912", + "arn": "arn:aws:us-east-1::event-source/aws.partner/bigcommerce.com/test/75fq9aqffI1I19pgc20b3xs8pulgqynm/final-test-1", + "eventSourceName": "final-test-1", + "eventSourceRegion": "US_EAST_1" + } + } + } + } +} +``` + + + + +#### Make note of the `event_source_arn` and `event_source_name` +Obtain the `event_source_arn` and `event_source_name` from the Graphql create event source mutation. You will not need them for the first iteration because there is no event source. After you create the event source, you will use these values later. You can save these fields in Postman as environment variables. + + +## Associate an event bus + +The next step is to associate the event source with a bus. You can associate an event by following the procedure below: + + + +```graphql filename="Example query: Create an Amazon event bus" showLineNumbers copy +POST https://events.{{region}}.amazonaws.com/?Action=CreateEventBus&Version=2015-10-07 +{ + "EventSourceName": "{{event_source_name}}", + "Name": "{{event_source_name}}" +} +``` + + +```graphql filename="Example response: Create an event bus" showLineNumbers copy +{ + "EventBusArn": "arn:aws:events:us-east-1:932486483912:event-bus/aws.partner/bigcommerce.com.test/75fq9aqffI1I9pgc20b3xs8pulgqynm/final-test-1" +} +``` + + + +For more information on how to create an event bus, see [CreateEventBus](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_CreateEventBus.html). + +## Create a rule + +Creating a rule helps to move specified events to the event bus otherwise, all events are ignored. + + + +```graphql filename="Example query: Create a rule" showLineNumbers copy +POST https://events.{{regions}}.amazonaws.com/?Action=PutRule&Version=2015-10-07 +{ + "Description": "Default rule to route all bigcommerce events.", + "EventBusName": "{{event_source_name}}", + "EventPattern": "{\"detail-type\":[\"bigCommerceWebhook\"]}", + "Name": "{{rule_name}}", + "State": "ENABLED" +} +``` + + +```graphql filename="Example response: Create a rule" showLineNumbers copy +{ + "RuleArn": "arn:aws:events:us-east-1:932486483912:rule/aws.partner/bigcommerce.com.test/75fq9aqffI1I9pgc20b3xs8pulgqynm/final-test-1/GenericRuleForBcEvents" +} +``` + + + +For more information on how to create or update a rule, see [PutRule](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutRule.html). + +## Apply a target to the rule + +Add the specific targets to the specified rule. This step allows SQS to receive message requests and check end-to-end delivery. + + + +```graphql filename="Example query: Put Targets" showLineNumbers copy +POST https://events.{{regions}}.amazonaws.com/?Action=PutTargets&Version=2015-10-07 +{ + "EventBusName": "{{event_source_name}}", + "Rule": "{{rule_name}}", + "Targets": [ + { + "Arn": "arn.aws:sqs:us-east-1:932486483912:{{sqs_name}}", + "Id": "{{sqs_id}}" + } +] +} +``` + + +```graphql filename="Example response: Put Targets" showLineNumbers copy +{ + "FailedEntries": [], + "FailedEntryCount": 0 +} +``` + + + +For more information on how to create an API destination, see [CreateApiDestination](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_CreateApiDestination.html). + +## Create an Amazon EventBridge webhook +Using GraphQL to create an Amazon EventBridge webhoook. + + + +```graphql filename="Example query: Create Amazon EventBridge" showLineNumbers copy +POST https://{{zone}}/stores/{{store_hash}}/graphql +mutation createAwsEventBridgeWebhook($input: CreateEventBridgeWebhookInput!){ + webhook { + createEventBridgeWebhook(input: $input) { + webhook { + id + scope + destination + isActive + createdAt + } + } + } +``` + +```graphql filename="GraphQL variables" showLineNumbers copy +{ + "input": { + "destination": "{{event_source_arn}}", + "isActive": true, + "scope": "store/category/updated" + } +} +``` + + +```graphql filename="Example response: Create Amazon EventBridge" showLineNumbers copy +{ + "data": { + "webhook": { + "createEventBridgeWebhook": { + "webhook": { + "id": "bc/store/webhook/29458", + "scope": "store/category/updated", + "destination": "arn:aws:events:us-east-1::event-source/aws.partner/bigcommerce.com/test/75fq9aqffI1I9pgc20b3xs8pulgqynm/final-test-1", + "isActive": true, + "createdAt": "2023-05-31T17:17:17z" + } + } + } + } + } +``` + + + +## Receive the event message + +The next step is to trigger the event to receive the event message. Although there is limited JSON support with the SQS API, you can use SQS Receive Messages to view the event message. + +For more information on Amazon Simple Queue Service (SQS), see [Amazon Simple Queue Service](https://aws.amazon.com/sqs/). From c51bc0084eaa0f2f52160f27577f7e73a4e84117 Mon Sep 17 00:00:00 2001 From: Traci Porter Date: Fri, 25 Apr 2025 09:57:52 -0500 Subject: [PATCH 4/4] Update text and links --- .../webhooks/aws-webhooks-overview.mdx | 35 +++++++++++-------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/docs/integrations/webhooks/aws-webhooks-overview.mdx b/docs/integrations/webhooks/aws-webhooks-overview.mdx index 6971d5a78..089b1c2f6 100644 --- a/docs/integrations/webhooks/aws-webhooks-overview.mdx +++ b/docs/integrations/webhooks/aws-webhooks-overview.mdx @@ -1,14 +1,18 @@ # Amazon Webhooks Overview -Amazon EventBridge is a serverless event bus that distributes events to connect application components and build highly scalable and resilient event-driven applications. It offers a simple way to consume webhook events from the BigCommerce platform at scale. +Amazon EventBridge is a serverless event bus that makes it easy to connect application components and build scalable, event-driven systems. With EventBridge, you can efficiently consume webhook events from the BigCommerce platform without managing your own webhook listener. -To use Amazon EventBridge, you must do the following: -* [Set up an event source](#set-up-an-event-source-not-available-in-beta) -* [Associate your event source with an event bus](#associate-an-event-bus-not-available-in-beta) -* [Create rules for the event bus](#create-a-rule-not-available-in-beta) -* Subscribe to webhooks +This guide walks you through the steps to integrate EventBridge with BigCommerce webhooks: + +* [Set up an event source](#set-up-an-event-source) +* [Associate your event source with an event bus](#associate-an-event-bus) +* [Create rules for the event bus](#create-a-rule) +* [Apply Targets to Rules](#apply-a-target-to-the-rule) +* [Create a Webhook](#create-an-amazon-eventbridge-webhook) +* [Receive the Event Message](#receive-the-event-message) ## Prerequisites + - To try out GraphQL queries and view responses, import our API examples into [Postman](https://www.getpostman.com/) or any other tool that allows testing of GraphQL queries. - Enter the following environment variables before starting: @@ -22,7 +26,7 @@ To use Amazon EventBridge, you must do the following: ## Set up an event source -Setting up an event source with EventBridge allows you to send event data to Amazon services directly instead of being responsible for receiving that traffic yourself through a front-end web server. You can set up an event source using a Create AWS Event Source query. +Setting up an event source with EventBridge allows you to send event data to Amazon services directly instead of being responsible for receiving that traffic yourself through a front-end web server. You can set up an event source using a Create AWS Event Source query. Use the following GraphQL mutation to create an event source: @@ -77,12 +81,12 @@ mutation createEventSource($input: CreateEventSourceInput!){ #### Make note of the `event_source_arn` and `event_source_name` -Obtain the `event_source_arn` and `event_source_name` from the Graphql create event source mutation. You will not need them for the first iteration because there is no event source. After you create the event source, you will use these values later. You can save these fields in Postman as environment variables. +Note: Save the `event_source_arn` and `event_source_name` from the response. While you won't need them during this step, you'll use them later to create the event bus and webhook. You can store them as environment variables in Postman. ## Associate an event bus -The next step is to associate the event source with a bus. You can associate an event by following the procedure below: +Now link the event source to an event bus using the following request: @@ -107,7 +111,7 @@ For more information on how to create an event bus, see [CreateEventBus](https:/ ## Create a rule -Creating a rule helps to move specified events to the event bus otherwise, all events are ignored. +A rule filters and routes events from the event bus to targets like SQS. Use this query to create one: @@ -135,7 +139,7 @@ For more information on how to create or update a rule, see [PutRule](https://do ## Apply a target to the rule -Add the specific targets to the specified rule. This step allows SQS to receive message requests and check end-to-end delivery. +Next, add a target (such as an SQS queue) to the rule to receive the webhook payloads: @@ -163,10 +167,11 @@ POST https://events.{{regions}}.amazonaws.com/?Action=PutTargets&Version=2015-10 -For more information on how to create an API destination, see [CreateApiDestination](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_CreateApiDestination.html). +For more information on how to apply a target, see [PutTargets](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutTargets.html). ## Create an Amazon EventBridge webhook -Using GraphQL to create an Amazon EventBridge webhoook. + +Use the GraphQL mutation below to create a BigCommerce webhook that sends events to EventBridge: @@ -219,6 +224,6 @@ mutation createAwsEventBridgeWebhook($input: CreateEventBridgeWebhookInput!){ ## Receive the event message -The next step is to trigger the event to receive the event message. Although there is limited JSON support with the SQS API, you can use SQS Receive Messages to view the event message. +Once everything is set up, trigger a webhook event (e.g., update a category) to send a message to SQS. Use the Receive Messages feature in Amazon SQS to inspect the payload. -For more information on Amazon Simple Queue Service (SQS), see [Amazon Simple Queue Service](https://aws.amazon.com/sqs/). +For more information on how to receive the event message, see [Amazon Simple Queue Service](https://aws.amazon.com/sqs/).