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

WebhookContext

WebhookContextWithoutSession<Topics> | WebhookContextWithSession<Topics>

WebhookContextWithoutSession

action
The action type: 'create', 'update', or 'delete'. Only available for events webhooks.
```
string
```
admin
```
undefined
```
apiVersion
The API version used for the webhook.
```
string
```
eventId
The unique event identifier.
```
string
```
handle
The handle for the webhook subscription. Only available for events webhooks.
```
string
```
name
The name assigned to the webhook subscription. Only available for traditional webhooks.
```
string
```
payload
The payload from the webhook request.
```
Record<string, any>
```
resourceId
The GID of the resource that triggered the webhook. Only available for events webhooks.
```
string
```
session
```
undefined
```
shop
The shop where the webhook was triggered.
```
string
```
subTopic
The sub-topic of the webhook. Only available for traditional webhooks.
```
string
```
topic
The topic of the webhook.
```
Topics
```
triggeredAt
The timestamp when the webhook was triggered.
```
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.
```
string
```
webhookType
The type of webhook: 'webhooks' for traditional webhooks or 'events' for events webhooks.
```
unknown
```

WebhookContextWithSession

action
The action type: 'create', 'update', or 'delete'. Only available for events webhooks.
```
string
```
admin
An admin context for the webhook. Returned only if there is a session for the shop.
```
AdminApiContext
```
apiVersion
The API version used for the webhook.
```
string
```
eventId
The unique event identifier.
```
string
```
handle
The handle for the webhook subscription. Only available for events webhooks.
```
string
```
name
The name assigned to the webhook subscription. Only available for traditional webhooks.
```
string
```
payload
The payload from the webhook request.
```
Record<string, any>
```
resourceId
The GID of the resource that triggered the webhook. Only available for events webhooks.
```
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.
```
unknown
```
shop
The shop where the webhook was triggered.
```
string
```
subTopic
The sub-topic of the webhook. Only available for traditional webhooks.
```
string
```
topic
The topic of the webhook.
```
Topics
```
triggeredAt
The timestamp when the webhook was triggered.
```
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.
```
string
```
webhookType
The type of webhook: 'webhooks' for traditional webhooks or 'events' for events webhooks.
```
unknown
```

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

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

Examples

/app/routes/**.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();

};

Examples

Description

Update a metafield when a product is updated

/app/routes/**.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

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

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

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

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

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

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

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

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

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

GraphQLClient

GraphQLQueryOptions

Anchor to RelatedRelated

Anchor to authenticate.webhook
authenticate.webhook(
request
)