Choose a version:

Webhook

Contains functions for verifying Shopify webhooks.

Note

The format of the admin object returned by this function changes with the v3_webhookAdminContext future flag. Learn more about gradual feature adoption.

Anchor to authenticate.webhook
authenticate.webhook(
request
)

Verifies requests coming from Shopify webhooks.

Anchor to authenticate.webhook-parametersParameters

Anchor to request request Request required

Anchor to authenticate.webhook-returnsReturns

Promise<<Future, Resources, Topics>>

WebhookContext

WebhookContextWithoutSession<Topics> | WebhookContextWithSession<Future, Resources, Topics>

WebhookContextWithoutSession

admin
```
undefined
```
apiVersion
The API version used for the webhook.
```
string
```
payload
The payload from the webhook request.
```
Record<string, any>
```
session
```
undefined
```
shop
The shop where the webhook was triggered.
```
string
```
subTopic
The sub-topic of the webhook. This is only available for certain webhooks.
```
string
```
topic
The topic of the webhook.
```
Topics
```
webhookId
A unique ID for the webhook. Useful to keep track of which events your app has already processed.
```
string
```

WebhookContextWithSession

admin
An admin context for the webhook. Returned only if there is a session for the shop.
```
WebhookAdminContext<Future, Resources>
```
apiVersion
The API version used for the webhook.
```
string
```
payload
The payload from the webhook request.
```
Record<string, any>
```
session
A session with an offline token for the shop. Returned only if there is a session for the shop.
```
Session
```
shop
The shop where the webhook was triggered.
```
string
```
subTopic
The sub-topic of the webhook. This is only available for certain webhooks.
```
string
```
topic
The topic of the webhook.
```
Topics
```
webhookId
A unique ID for the webhook. Useful to keep track of which events your app has already processed.
```
string
```

WebhookAdminContext

FeatureEnabled<Future, 'v3_webhookAdminContext'> extends true
    ? AdminApiContext<Resources>
    : LegacyWebhookAdminApiContext<Resources>

FeatureEnabled

Future extends FutureFlags
  ? Future[Flag] extends true
    ? true
    : false
  : false

FutureFlags

Set future flags using the `future` configuration field to opt in to upcoming breaking changes. With this feature, you can prepare for major releases ahead of time, as well as try out new features before they are released.

unstable_newEmbeddedAuthStrategy
When enabled, embedded apps will fetch access tokens via [token exchange](/docs/apps/auth/get-access-tokens/token-exchange). This assumes the app has scopes declared for [Shopify managing installation](/docs/apps/auth/installation#shopify-managed-installation). Learn more about this [new embedded app auth strategy](/docs/api/shopify-app-remix#embedded-auth-strategy).
```
boolean
```
v3_authenticatePublic
When enabled authenticate.public() will not work. Use authenticate.public.checkout() instead.
```
boolean
```
v3_lineItemBilling
When enabled allows you to pass billing plans with line items when creating a new app subscriptions.
```
boolean
```
v3_webhookAdminContext
When enabled, returns the same `admin` context (`AdminApiContext`) from `authenticate.webhook` that is returned from `authenticate.admin`.
```
boolean
```

AdminApiContext

Provides utilities that apps can use to make requests to the Admin API.

graphql
Methods for interacting with the Shopify Admin GraphQL API
```
GraphQLClient<AdminOperations>
```
rest
Methods for interacting with the Shopify Admin REST API There are methods for interacting with individual REST resources. You can also make `GET`, `POST`, `PUT` and `DELETE` requests should the REST resources not meet your needs.
```
RestClientWithResources<Resources>
```

GraphQLClient

query
```
Operation extends keyof Operations
```

options

GraphQLQueryOptions<Operation, Operations>

returns

interface Promise<T> {
    /**
     * Attaches callbacks for the resolution and/or rejection of the Promise.
     * @param onfulfilled The callback to execute when the Promise is resolved.
     * @param onrejected The callback to execute when the Promise is rejected.
     * @returns A Promise for the completion of which ever callback is executed.
     */
    then<TResult1 = T, TResult2 = never>(onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;

    /**
     * Attaches a callback for only the rejection of the Promise.
     * @param onrejected The callback to execute when the Promise is rejected.
     * @returns A Promise for the completion of the callback.
     */
    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null): Promise<T | TResult>;
}, interface Promise<T> {}, Promise: PromiseConstructor, interface Promise<T> {
    readonly [Symbol.toStringTag]: string;
}, interface Promise<T> {
    /**
     * Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The
     * resolved value cannot be modified from the callback.
     * @param onfinally The callback to execute when the Promise is settled (fulfilled or rejected).
     * @returns A Promise for the completion of the callback.
     */
    finally(onfinally?: (() => void) | undefined | null): Promise<T>;
}

GraphQLQueryOptions

apiVersion
The version of the API to use for the request.
```
ApiVersion
```
headers
Additional headers to include in the request.
```
Record<string, any>
```
tries
The total number of times to try the request if it fails.
```
number
```
variables
The variables to pass to the operation.
```
ApiClientRequestOptions<Operation, Operations>
```

RestClientWithResources

RemixRestClient & {resources: Resources}

RemixRestClient

session
```
Session
```

get

Performs a GET request on the given path.

(params: GetRequestParams) => Promise<Response>

post

Performs a POST request on the given path.

(params: PostRequestParams) => Promise<Response>

put

Performs a PUT request on the given path.

(params: PostRequestParams) => Promise<Response>

delete
Performs a DELETE request on the given path.
```
(params: GetRequestParams) => Promise<Response>
```

LegacyWebhookAdminApiContext

graphql

A GraphQL client.

InstanceType<Shopify['clients']['Graphql']>

rest
A REST client.
```
RestClient & Resources
```

Examples

/app/routes/**.ts

import {type ActionFunctionArgs} from '@remix-run/node';

import {authenticate} from '../shopify.server';

export const action = async ({request}: ActionFunctionArgs) => {

const {topic, admin, payload} = await authenticate.webhook(request);

switch (topic) {

case 'PRODUCTS_UPDATE':

await admin.graphql(

`#graphql

mutation setMetafield($productId: ID!, $time: String!) {

metafieldsSet(metafields: {

ownerId: $productId

namespace: "my-app",

key: "webhook_received_at",

value: $time,

type: "string",

}) {

metafields {

key

value

}

{

variables: {

productId: payload.admin_graphql_api_id,

time: new Date().toISOString(),

);

return new Response();

}

throw new Response();

};

Examples

Description

Update a metafield when a product is updated

/app/routes/**.ts

import {type ActionFunctionArgs} from '@remix-run/node';

import {authenticate} from '../shopify.server';

export const action = async ({request}: ActionFunctionArgs) => {
  const {topic, admin, payload} = await authenticate.webhook(request);

  switch (topic) {
    case 'PRODUCTS_UPDATE':
      await admin.graphql(
        `#graphql
        mutation setMetafield($productId: ID!, $time: String!) {
          metafieldsSet(metafields: {
            ownerId: $productId
            namespace: "my-app",
            key: "webhook_received_at",
            value: $time,
            type: "string",
          }) {
            metafields {
              key
              value
            }
          }
        }
        `,
        {
          variables: {
            productId: payload.admin_graphql_api_id,
            time: new Date().toISOString(),
          },
        },
      );

      return new Response();
  }

  throw new Response();
};

Description

With the `v3_webhookAdminContext` future flag enabled, use the `admin` object in the context to interact with the Admin API.

/app/routes/webhooks.tsx

import { ActionFunctionArgs } from "@remix-run/node";
import { authenticate } from "../shopify.server";

export async function action({ request }: ActionFunctionArgs) {
  const { admin } = await authenticate.webhook(request);

  const response = await admin?.graphql(
    `#graphql
    mutation populateProduct($input: ProductInput!) {
      productCreate(input: $input) {
        product {
          id
        }
      }
    }`,
    { variables: { input: { title: "Product Name" } } }
  );

  const productData = await response.json();
  return json({ data: productData.data });
}

Description

Use the `admin` object in the context to interact with the Admin API. This format will be removed in V3 of the package.

/app/routes/webhooks.tsx

import { json, ActionFunctionArgs } from "@remix-run/node";
import { authenticate } from "../shopify.server";

export async function action({ request }: ActionFunctionArgs) {
  const { admin } = await authenticate.webhook(request);

  const response = await admin?.graphql.query<any>({
    data: {
      query: `#graphql
        mutation populateProduct($input: ProductInput!) {
          productCreate(input: $input) {
            product {
              id
            }
          }
        }`,
      variables: { input: { title: "Product Name" } },
    },
  });

  const productData = response?.body.data;
  return json({ data: productData.data });
}

Description

Get the API version used for webhook request.

/app/routes/webhooks.tsx

import { ActionFunctionArgs } from "@remix-run/node";
import { authenticate } from "../shopify.server";

export const action = async ({ request }: ActionFunctionArgs) => {
  const { apiVersion } = await authenticate.webhook(request);
  return new Response();
};

Description

Get the request's POST payload.

/app/routes/webhooks.tsx

import { ActionFunctionArgs } from "@remix-run/node";
import { authenticate } from "../shopify.server";

export const action = async ({ request }: ActionFunctionArgs) => {
  const { payload } = await authenticate.webhook(request);
  return new Response();
};

Description

Get the shop that triggered a webhook.

/app/routes/webhooks.tsx

import { ActionFunctionArgs } from "@remix-run/node";
import { authenticate } from "../shopify.server";

export const action = async ({ request }: ActionFunctionArgs) => {
  const { shop } = await authenticate.webhook(request);
  return new Response();
};

Description

Get the webhook sub-topic.

/app/routes/webhooks.tsx

import { ActionFunctionArgs } from "@remix-run/node";
import { authenticate } from "../shopify.server";

export const action = async ({ request }: ActionFunctionArgs) => {
  const { subTopic } = await authenticate.webhook(request);
  return new Response();
};

Description

Get the event topic for the webhook.

/app/routes/webhooks.tsx

import { ActionFunctionArgs } from "@remix-run/node";
import { authenticate } from "../shopify.server";

export const action = async ({ request }: ActionFunctionArgs) => {
  const { topic } = await authenticate.webhook(request);

  switch (topic) {
    case "APP_UNINSTALLED":
      // Do something when the app is uninstalled.
      break;
  }

  return new Response();
};

Description

Get the webhook ID.

/app/routes/webhooks.tsx

import { ActionFunctionArgs } from "@remix-run/node";
import { authenticate } from "../shopify.server";

export const action = async ({ request }: ActionFunctionArgs) => {
  const { webhookId } = await authenticate.webhook(request);
  return new Response();
};