Webhook
Contains functions for verifying Shopify webhooks.
Verifies requests coming from Shopify webhooks.
- Anchor to requestrequestrequestRequestRequestrequiredrequired
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 - 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.
WebhookTypeValue
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.
Session - shop
The shop where the webhook was triggered.
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.
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
GraphQLClient<AdminOperations>
GraphQLClient
- query
Operation extends keyof Operations - options
GraphQLQueryOptions<Operation, Operations>
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>["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.
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 - refreshToken
The refresh token for the session.
string - refreshTokenExpires
The date the refresh token expires.
Date - 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 - refreshToken
The refresh token for the session.
string - refreshTokenExpires
The date the refresh token expires.
Date - 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>;
}/app/routes/**.ts
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 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(); };
