Buy with Prime | Developer Documentation
Documentation

Steps to Subscribe to Buy with Prime Events Using Webhook Events

📘

Buy with Prime API is now available for early access

Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.

Sign Up

You can subscribe and receive notifications for Buy with Prime events as webhook events or using Amazon EventBridge. For details on subscribing to Buy with Prime events using Amazon EventBridge, see Steps to Subscribe to Buy with Prime Events using Amazon EventBridge.

Prerequisites

  • To receive webhook events, you must have an HTTPS endpoint that accepts webhook events.

  • To rotate client authorization credentials or use the same authorization credentials for multiple event subscriptions, generate an authProfileId by creating an authentication profile.

Create an authentication profile

The createAuthProfile mutation lets you create a reusable authentication profile for webhook destinations. createAuthProfile supports creation of authentication profiles using both OAuth 2.0 and HTTP basic authentication configurations.

If you don't need to rotate or reuse your client credentials, you don't need an authProfileId to subscribe to webhook events. If you use an authProfileId, including an x-amzn-signature in your request header is optional.

Option 1: Create an authentication profile using OAuth 2.0 client credentials

The following example shows a createAuthProfile request that creates an authentication profile using the provided OAuth 2.0 client credentials. The response contains an authProfileId that you use to subscribe to webhook events. You can specify a value for authProfileId by including the optional authProfileAliasId in your request. If you do not include a value for authProfileAliasId, the API generates a default authProfileId.

Request 
mutation {
    createAuthProfile(
        input: {
            // Optional
            authProfileAliasId: "example-authprofilealiasid",
            authConfig: {
                // Required
                oAuthConfig: {
                    clientParameters: {
                        clientId: "example-client-id",
                        clientSecret: "example-client-secret"
                    },
                    authEndpoint: "example-endpoint-url",
                    httpMethod: "POST",
                    httpParameters: {
                        bodyParameters: [
                            {
                                key: "grant_type",
                                value: "client_credentials"
                            },
                            {
                                key: "scope",
                                value: "write:order"
                            }
                        ],
                        headerParameters: [
                            {
                                key: "Content-Type",
                                value: "application/x-www-form-urlencoded"
                            }
                        ]
                    }
                }
            }
        }
    ) {
        authProfileId
    }
}
Response 
{
  "data": {
    "createAuthProfile": {
      "authProfileId": "example-authprofileid"
    }
  }
}

Option 2: Create an authentication profile using HTTP basic authentication

The following example shows a createAuthProfile mutation that creates an authentication profile using a provided username and password. The response contains an authProfileId that you use to subscribe to webhook events. You can specify a value for authProfileId by including the optional authProfileAliasId in your request. If you do not include a value for authProfileAliasId, the API generates a default authProfileId.

Request 
mutation {
    createAuthProfile(
        input: {
            // Optional
            authProfileAliasId: "example-authprofilealiasid",
            authConfig: {
                // Required
                basicAuthConfig: {
                    username: "example-username",
                    password: "example-password"
                }
            }
        }
    ) {
        authProfileId
    }
}
Response 
{
  "data": {
    "createAuthProfile": {
      "authProfileId": "example-authprofileid"
    }
  }
}

Update an authentication profile

Use the updateAuthProfile mutation to update values within an authentication profile. Any changes made to an authentication profile apply to all webhook event subscriptions that use that authentication profile.

The following example shows an updateAuthProfile request that updates an OAuth 2.0 authentication profile with new client credentials.

Request 
mutation {
    updateAuthProfile(
        input: {
            authProfileId: "example-authprofileid",
            authConfig: {
                oAuthConfig: {
                    clientParameters: {
                        clientId: "example-new-clientid",
                        clientSecret: "example-new-clientsecret"
                    },
                    authEndpoint: "example-endpoint-url",
                    httpMethod: "POST",
                    httpParameters: {
                        bodyParameters: [
                            {
                                key: "grant_type",
                                value: "client_credentials"
                            },
                            {
                                key: "scope",
                                value: "write:order"
                            }
                        ],
                        headerParameters: [
                            {
                                key: "Content-Type",
                                value: "application/x-www-form-urlencoded"
                            }
                        ]
                    }
                }
            }
        }
    ) {
        authProfileId
    }
}
Response 
{
  "data": {
    "updateAuthProfile": {
      "authProfileId": "example-authprofileid"
    }
  }
}

The following example shows an updateAuthProfile request that updates an authentication profile using HTTP basic authentication.

Request 
mutation {
    updateAuthProfile(
        input: {
            authProfileId: "example-authprofileid",
            authConfig: {            
                basicAuthConfig: {
                    username: "example-new-username",
                    password: "example-new-password"
                }
            }
        }
    ) {
        authProfileId
    }
}
Response 
{
  "data": {
    "updateAuthProfile": {
      "authProfileId": "example-authprofileid"
    }
  }
}

Delete authentication profiles when no longer in use

Use the deleteAuthProfile mutation to delete authentication profiles that are no longer in use. The following example shows a successful deleteAuthProfile request.

Request 
mutation {
    deleteAuthProfile(
        authProfileId: "example-authprofileid"
    ) {
        authProfile {
            authProfileId
        }
    }
}
Response 
{
  "data": {
    "deleteAuthProfile": {
      "authProfileId": "example-authprofileid"
    }
  }
}

If you attempt to delete an authentication profile referenced by active webhook subscriptions, the deleteAuthProfile request generates a response with an error message.

Create event subscriptions

To receive events from Buy with Prime, call the createEventSubscription mutation. For details, see Create and Delete Event Subscriptions.

The API call requires the following information:

  • HTTP method: The HTTP method your webhook endpoint accepts.
  • Webhook URL: Your webhook endpoint.
  • Authentication Profile ID: Your authentication profile ID for Buy with Prime webhook destinations.
  • Event types: The types of events you want to subscribe to.

Related topics

Updated about 21 hours ago