Choose a version:

Webhook

Contains functions for verifying Shopify webhooks.

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<<ConfigArg, Resources, Topics>>

WebhookContext

WebhookContextWithoutSession<Topics> | WebhookContextWithSession<ConfigArg, 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.
```
AdminApiContext<ConfigArg, 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. Webhook requests can trigger after an app is uninstalled If the app is already uninstalled, the session may be undefined. Therefore, you should check for the session before using it.
```
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
```

AdminApiContext

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

FeatureEnabled<ConfigArg['future'], 'removeRest'> extends true
    ? AdminApiContextWithoutRest
    : AdminApiContextWithRest<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.

removeRest
When enabled, methods for interacting with the admin REST API will not be returned. This affects: * `authenticate.admin(request)` * `authenticate.webhook(request)` * `authenticate.flow(request)` * `authenticate.appProxy(request)` * `authenticate.fulfillmentService(request)` * `unauthenticated.admin(shop)` In a future release we will remove REST from the package completely. Please see: [https://www.shopify.com/ca/partners/blog/all-in-on-graphql](https://www.shopify.com/ca/partners/blog/all-in-on-graphql)
```
boolean
```
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
```

AdminApiContextWithoutRest

graphql
Methods for interacting with the Shopify Admin GraphQL API
```
GraphQLClient<AdminOperations>
```

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>
```
signal
An optional AbortSignal to cancel the request.
```
AbortSignal
```
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>
```

ApiVersion

October24
```
2024-10
```
January25
```
2025-01
```
April25
```
2025-04
```
July25
```
2025-07
```
October25
```
2025-10
```
January26
```
2026-01
```
April26
```
2026-04
```
Unstable
```
unstable
```

AdminApiContextWithRest

graphql
Methods for interacting with the Shopify Admin GraphQL API
```
GraphQLClient<AdminOperations>
```
rest
Methods for interacting with the Shopify Admin REST API
```
RestClientWithResources<Resources>
```

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>
```

Session

Stores App information from logged in merchants so they can make authenticated requests to the Admin API.

id
The unique identifier for the session.
```
string
```
shop
The Shopify shop domain, such as `example.myshopify.com`.
```
string
```
state
The state of the session. Used for the OAuth authentication code flow.
```
string
```
isOnline
Whether the access token in the session is online or offline.
```
boolean
```
scope
The desired scopes for the access token, at the time the session was created.
```
string
```
expires
The date the access token expires.
```
Date
```
accessToken
The access token for the session.
```
string
```
onlineAccessInfo
Information on the user for the session. Only present for online sessions.
```
OnlineAccessInfo
```
isActive
Whether the session is active. Active sessions have an access token that is not expired, and has has the given scopes if scopes is equal to a truthy value.
```
(scopes: string | string[] | AuthScopes, withinMillisecondsOfExpiry?: number) => boolean
```
isScopeChanged
Whether the access token includes the given scopes if they are provided.
```
(scopes: string | string[] | AuthScopes) => boolean
```
isScopeIncluded
Whether the access token includes the given scopes.
```
(scopes: string | string[] | AuthScopes) => boolean
```

isExpired

Whether the access token is expired.

(withinMillisecondsOfExpiry?: number) => boolean

toObject
Converts an object with data into a Session.
```
() => SessionParams
```
equals
Checks whether the given session is equal to this session.
```
(other: Session) => boolean
```
toPropertyArray
Converts the session into an array of key-value pairs.
```
(returnUserData?: boolean) => [string, string | number | boolean][]
```

OnlineAccessInfo

associated_user
The user associated with the access token.
```
OnlineAccessUser
```
associated_user_scope
The effective set of scopes for the session.
```
string
```
expires_in
How long the access token is valid for, in seconds.
```
number
```

OnlineAccessUser

account_owner
Whether the user is the account owner.
```
boolean
```
collaborator
Whether the user is a collaborator.
```
boolean
```
email
The user's email address.
```
string
```
email_verified
Whether the user has verified their email address.
```
boolean
```
first_name
The user's first name.
```
string
```
id
The user's ID.
```
number
```
last_name
The user's last name.
```
string
```
locale
The user's locale.
```
string
```

AuthScopes

A class that represents a set of access token scopes.

has
Checks whether the current set of scopes includes the given one.
```
(scope: string | string[] | AuthScopes) => boolean
```
equals
Checks whether the current set of scopes equals the given one.
```
(otherScopes: string | string[] | AuthScopes) => boolean
```
toString
Returns a comma-separated string with the current set of scopes.
```
() => string
```
toArray
Returns an array with the current set of scopes.
```
(returnOriginalScopes?: boolean) => any[]
```

SessionParams

[key: string]
```
any
```
accessToken
The access token for the session.
```
string
```
expires
The date the access token expires.
```
Date
```
id
The unique identifier for the session.
```
string
```
isOnline
Whether the access token in the session is online or offline.
```
boolean
```
onlineAccessInfo
Information on the user for the session. Only present for online sessions.
```
OnlineAccessInfo | StoredOnlineAccessInfo
```
scope
The scopes for the access token.
```
string
```
shop
The Shopify shop domain.
```
string
```
state
The state of the session. Used for the OAuth authentication code flow.
```
string
```

StoredOnlineAccessInfo

Omit<OnlineAccessInfo, 'associated_user'> & {
  associated_user: Partial<OnlineAccessUser>;
}

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, session} = await authenticate.webhook(request);

// Webhook requests can trigger after an app is uninstalled

// If the app is already uninstalled, the session may be undefined.

if (!session) {

throw new Response();

}

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();

};

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, session} = await authenticate.webhook(request);

  // Webhook requests can trigger after an app is uninstalled
  // If the app is already uninstalled, the session may be undefined.
  if (!session) {
    throw new Response();
  }

  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();
};

Description

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);

  // Webhook requests can trigger after an app is uninstalled
  // If the app is already uninstalled, the session may be undefined.
  if (!session) {
    throw new Response();
  }

  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

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();
};

/app/routes/webhooks.tsx

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

export const action = async ({ request }: ActionFunctionArgs) => {
  const { session } = await authenticate.webhook(request);
  
  // Webhook requests can trigger after an app is uninstalled
  // If the app is already uninstalled, the session may be undefined.
  if (!session) {
    throw new Response();
  }

  // Handle webhook request
  console.log("Received webhook webhook");

  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();
};

Anchor to RelatedRelated

Interact with the Admin API.Admin API context

Was this page helpful?

Anchor to authenticate.webhookauthenticate.webhook(requestrequest)

Anchor to authenticate.webhook-parametersParameters

Anchor to authenticate.webhook-returnsReturns

WebhookContext

WebhookContextWithoutSession

WebhookContextWithSession

AdminApiContext

FeatureEnabled

FutureFlags

AdminApiContextWithoutRest

GraphQLClient

GraphQLQueryOptions

ApiVersion

AdminApiContextWithRest

RestClientWithResources

RemixRestClient

Session

OnlineAccessInfo

OnlineAccessUser

AuthScopes

SessionParams

StoredOnlineAccessInfo

Anchor to RelatedRelated

Anchor to authenticate.webhook
authenticate.webhook(
request
)