---
title: Webhook
description: Contains functions for verifying Shopify webhooks.
api_version: v1
source_url:
  html: >-
    https://shopify.dev/docs/api/shopify-app-react-router/v1/authenticate/webhook
  md: >-
    https://shopify.dev/docs/api/shopify-app-react-router/v1/authenticate/webhook.md
api_name: shopify-app-react-router
---

# Webhook

Contains functions for verifying Shopify webhooks.

## authenticate.​webhook(**[request](#authenticatewebhook-propertydetail-request)**​)

Verifies requests coming from Shopify webhooks.

### Parameters

* **request**

  **Request**

  **required**

### Returns

* **Promise\<WebhookContext\<Topics>>**

### WebhookContext

```ts
WebhookContextWithoutSession<Topics> | WebhookContextWithSession<Topics>
```

### WebhookContextWithoutSession

* action

  The action type: 'create', 'update', or 'delete'. Only available for events webhooks.

  ```ts
  string
  ```

* admin

  ```ts
  undefined
  ```

* apiVersion

  The API version used for the webhook.

  ```ts
  string
  ```

* eventId

  The unique event identifier.

  ```ts
  string
  ```

* handle

  The handle for the webhook subscription. Only available for events webhooks.

  ```ts
  string
  ```

* name

  The name assigned to the webhook subscription. Only available for traditional webhooks.

  ```ts
  string
  ```

* payload

  The payload from the webhook request.

  ```ts
  Record<string, any>
  ```

* resourceId

  The GID of the resource that triggered the webhook. Only available for events webhooks.

  ```ts
  string
  ```

* session

  ```ts
  undefined
  ```

* shop

  The shop where the webhook was triggered.

  ```ts
  string
  ```

* topic

  The topic of the webhook.

  ```ts
  Topics
  ```

* triggeredAt

  The timestamp when the webhook was triggered.

  ```ts
  string
  ```

* webhookId

  A unique ID for the webhook. This is the idempotency key — useful to keep track of which events your app has already processed.

  ```ts
  string
  ```

* webhookType

  The type of webhook: 'webhooks' for traditional webhooks or 'events' for events webhooks.

  ```ts
  WebhookTypeValue
  ```

### WebhookContextWithSession

* action

  The action type: 'create', 'update', or 'delete'. Only available for events webhooks.

  ```ts
  string
  ```

* admin

  An admin context for the webhook. Returned only if there is a session for the shop.

  ```ts
  AdminApiContext
  ```

* apiVersion

  The API version used for the webhook.

  ```ts
  string
  ```

* eventId

  The unique event identifier.

  ```ts
  string
  ```

* handle

  The handle for the webhook subscription. Only available for events webhooks.

  ```ts
  string
  ```

* name

  The name assigned to the webhook subscription. Only available for traditional webhooks.

  ```ts
  string
  ```

* payload

  The payload from the webhook request.

  ```ts
  Record<string, any>
  ```

* resourceId

  The GID of the resource that triggered the webhook. Only available for events webhooks.

  ```ts
  string
  ```

* 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.

  ```ts
  Session
  ```

* shop

  The shop where the webhook was triggered.

  ```ts
  string
  ```

* topic

  The topic of the webhook.

  ```ts
  Topics
  ```

* triggeredAt

  The timestamp when the webhook was triggered.

  ```ts
  string
  ```

* webhookId

  A unique ID for the webhook. This is the idempotency key — useful to keep track of which events your app has already processed.

  ```ts
  string
  ```

* webhookType

  The type of webhook: 'webhooks' for traditional webhooks or 'events' for events webhooks.

  ```ts
  WebhookTypeValue
  ```

### AdminApiContext

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

* graphql

  Methods for interacting with the Shopify Admin GraphQL API

  ```ts
  GraphQLClient<AdminOperations>
  ```

### GraphQLClient

* query

  ```ts
  Operation extends keyof Operations
  ```

* options

  ```ts
  GraphQLQueryOptions<Operation, Operations>
  ```

returns

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

  ```ts
  ApiVersion
  ```

* headers

  Additional headers to include in the request.

  ```ts
  Record<string, any>
  ```

* signal

  An optional AbortSignal to cancel the request.

  ```ts
  AbortSignal
  ```

* tries

  The total number of times to try the request if it fails.

  ```ts
  number
  ```

* variables

  The variables to pass to the operation.

  ```ts
  ApiClientRequestOptions<Operation, Operations>["variables"]
  ```

### 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.

  ```ts
  string
  ```

* shop

  The Shopify shop domain, such as \`example.myshopify.com\`.

  ```ts
  string
  ```

* state

  The state of the session. Used for the OAuth authentication code flow.

  ```ts
  string
  ```

* isOnline

  Whether the access token in the session is online or offline.

  ```ts
  boolean
  ```

* scope

  The desired scopes for the access token, at the time the session was created.

  ```ts
  string
  ```

* expires

  The date the access token expires.

  ```ts
  Date
  ```

* accessToken

  The access token for the session.

  ```ts
  string
  ```

* refreshToken

  The refresh token for the session.

  ```ts
  string
  ```

* refreshTokenExpires

  The date the refresh token expires.

  ```ts
  Date
  ```

* onlineAccessInfo

  Information on the user for the session. Only present for online sessions.

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

  ```ts
  (scopes: string | string[] | AuthScopes, withinMillisecondsOfExpiry?: number) => boolean
  ```

* isScopeChanged

  Whether the access token includes the given scopes if they are provided.

  ```ts
  (scopes: string | string[] | AuthScopes) => boolean
  ```

* isScopeIncluded

  Whether the access token includes the given scopes.

  ```ts
  (scopes: string | string[] | AuthScopes) => boolean
  ```

* isExpired

  Whether the access token is expired.

  ```ts
  (withinMillisecondsOfExpiry?: number) => boolean
  ```

* toObject

  Converts an object with data into a Session.

  ```ts
  () => SessionParams
  ```

* equals

  Checks whether the given session is equal to this session.

  ```ts
  (other: Session) => boolean
  ```

* toPropertyArray

  Converts the session into an array of key-value pairs.

  ```ts
  (returnUserData?: boolean) => [string, string | number | boolean][]
  ```

### OnlineAccessInfo

* associated\_user

  The user associated with the access token.

  ```ts
  OnlineAccessUser
  ```

* associated\_user\_scope

  The effective set of scopes for the session.

  ```ts
  string
  ```

* expires\_in

  How long the access token is valid for, in seconds.

  ```ts
  number
  ```

### OnlineAccessUser

* account\_owner

  Whether the user is the account owner.

  ```ts
  boolean
  ```

* collaborator

  Whether the user is a collaborator.

  ```ts
  boolean
  ```

* email

  The user's email address.

  ```ts
  string
  ```

* email\_verified

  Whether the user has verified their email address.

  ```ts
  boolean
  ```

* first\_name

  The user's first name.

  ```ts
  string
  ```

* id

  The user's ID.

  ```ts
  number
  ```

* last\_name

  The user's last name.

  ```ts
  string
  ```

* locale

  The user's locale.

  ```ts
  string
  ```

### AuthScopes

A class that represents a set of access token scopes.

* has

  Checks whether the current set of scopes includes the given one.

  ```ts
  (scope: string | string[] | AuthScopes) => boolean
  ```

* equals

  Checks whether the current set of scopes equals the given one.

  ```ts
  (otherScopes: string | string[] | AuthScopes) => boolean
  ```

* toString

  Returns a comma-separated string with the current set of scopes.

  ```ts
  () => string
  ```

* toArray

  Returns an array with the current set of scopes.

  ```ts
  (returnOriginalScopes?: boolean) => any[]
  ```

### SessionParams

* \[key: string]

  ```ts
  any
  ```

* accessToken

  The access token for the session.

  ```ts
  string
  ```

* expires

  The date the access token expires.

  ```ts
  Date
  ```

* id

  The unique identifier for the session.

  ```ts
  string
  ```

* isOnline

  Whether the access token in the session is online or offline.

  ```ts
  boolean
  ```

* onlineAccessInfo

  Information on the user for the session. Only present for online sessions.

  ```ts
  OnlineAccessInfo | StoredOnlineAccessInfo
  ```

* refreshToken

  The refresh token for the session.

  ```ts
  string
  ```

* refreshTokenExpires

  The date the refresh token expires.

  ```ts
  Date
  ```

* scope

  The scopes for the access token.

  ```ts
  string
  ```

* shop

  The Shopify shop domain.

  ```ts
  string
  ```

* state

  The state of the session. Used for the OAuth authentication code flow.

  ```ts
  string
  ```

### StoredOnlineAccessInfo

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

Examples

### Examples

* ####

  ##### Description

  Update a metafield when a product is updated

  ##### /app/routes/\*\*.ts

  ```ts
  import {type ActionFunctionArgs} from 'react-router';

  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

  ```ts
  import { ActionFunctionArgs } from "react-router";
  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 ({ data: productData.data });
  }
  ```

* ####

  ##### Description

  Get the API version used for webhook request.

  ##### /app/routes/webhooks.tsx

  ```ts
  import { ActionFunctionArgs } from "react-router";
  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

  ```ts
  import { ActionFunctionArgs } from "react-router";
  import { authenticate } from "../shopify.server";

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

* ####

  ##### /app/routes/webhooks.tsx

  ```ts
  import type { ActionFunctionArgs } from "react-router";
  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

  ```ts
  import { ActionFunctionArgs } from "react-router";
  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

  ```ts
  import { ActionFunctionArgs } from "react-router";
  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

  ```ts
  import { ActionFunctionArgs } from "react-router";
  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

  ```ts
  import { ActionFunctionArgs } from "react-router";
  import { authenticate } from "../shopify.server";

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

***

## Related

[Interact with the Admin API. - Admin API context](https://shopify.dev/docs/api/shopify-app-react-router/v1/apis/admin-api)

***