---
title: webhookSubscriptionDelete - GraphQL Admin
description: |-
  Removes an existing webhook subscription, stopping all future event notifications for that subscription. This mutation provides a clean way to deactivate webhooks when they're no longer needed.

  For example, when an app feature is disabled or when you need to change webhook configurations, you can delete
  the old webhook subscription to prevent unnecessary event delivery and potential errors. Alternatively, for
  endpoint changes, you might consider updating the existing subscription instead of deleting and recreating it.

  Use `webhookSubscriptionDelete` to:
  - Clean up unused webhook subscriptions
  - Stop event delivery to deprecated endpoints
  - Remove subscriptions during app uninstallation
  - Reduce unnecessary resource usage by removing unused subscriptions

  The mutation returns the deleted subscription's ID for confirmation when successful. Validation errors are included in the response if you request them in your query, as with all GraphQL mutations.

  Learn more about [managing webhook subscriptions](https://shopify.dev/docs/apps/build/webhooks/subscribe).


  Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your `shopify.app.toml` may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read [About managing webhook subscriptions](https://shopify.dev/docs/apps/build/webhooks/subscribe).
api_version: 2025-10
api_name: admin
type: mutation
api_type: graphql
source_url:
  html: https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionDelete?example=remove-an-existing-webhook
  md: https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionDelete.md?example=remove-an-existing-webhook
---

# webhook​Subscription​Delete

mutation

Removes an existing webhook subscription, stopping all future event notifications for that subscription. This mutation provides a clean way to deactivate webhooks when they're no longer needed.

For example, when an app feature is disabled or when you need to change webhook configurations, you can delete the old webhook subscription to prevent unnecessary event delivery and potential errors. Alternatively, for endpoint changes, you might consider updating the existing subscription instead of deleting and recreating it.

Use `webhookSubscriptionDelete` to:

* Clean up unused webhook subscriptions
* Stop event delivery to deprecated endpoints
* Remove subscriptions during app uninstallation
* Reduce unnecessary resource usage by removing unused subscriptions

The mutation returns the deleted subscription's ID for confirmation when successful. Validation errors are included in the response if you request them in your query, as with all GraphQL mutations.

Learn more about [managing webhook subscriptions](https://shopify.dev/docs/apps/build/webhooks/subscribe).

Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your `shopify.app.toml` may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read [About managing webhook subscriptions](https://shopify.dev/docs/apps/build/webhooks/subscribe).

## Arguments

* id

  [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID)

  required

  The ID of the webhook subscription to delete.

***

## Webhook​Subscription​Delete​Payload returns

* deleted​Webhook​Subscription​Id

  [ID](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID)

  The ID of the deleted webhook subscription.

* user​Errors

  [\[User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/UserError)

  non-null

  The list of errors that occurred from executing the mutation.

***

## Examples

* ### Remove an existing Webhook

  #### Query

  ```graphql
  mutation webhookSubscriptionDelete($id: ID!) {
    webhookSubscriptionDelete(id: $id) {
      userErrors {
        field
        message
      }
      deletedWebhookSubscriptionId
    }
  }
  ```

  #### Variables

  ```json
  {
    "id": "gid://shopify/WebhookSubscription/525699895"
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "mutation webhookSubscriptionDelete($id: ID!) { webhookSubscriptionDelete(id: $id) { userErrors { field message } deletedWebhookSubscriptionId } }",
   "variables": {
      "id": "gid://shopify/WebhookSubscription/525699895"
    }
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    mutation webhookSubscriptionDelete($id: ID!) {
      webhookSubscriptionDelete(id: $id) {
        userErrors {
          field
          message
        }
        deletedWebhookSubscriptionId
      }
    }`,
    {
      variables: {
          "id": "gid://shopify/WebhookSubscription/525699895"
      },
    },
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    mutation webhookSubscriptionDelete($id: ID!) {
      webhookSubscriptionDelete(id: $id) {
        userErrors {
          field
          message
        }
        deletedWebhookSubscriptionId
      }
    }
  QUERY

  variables = {
    "id": "gid://shopify/WebhookSubscription/525699895"
  }

  response = client.query(query: query, variables: variables)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `mutation webhookSubscriptionDelete($id: ID!) {
        webhookSubscriptionDelete(id: $id) {
          userErrors {
            field
            message
          }
          deletedWebhookSubscriptionId
        }
      }`,
      "variables": {
          "id": "gid://shopify/WebhookSubscription/525699895"
      },
    },
  });
  ```

  #### Response

  ```json
  {
    "webhookSubscriptionDelete": {
      "userErrors": [],
      "deletedWebhookSubscriptionId": "gid://shopify/WebhookSubscription/525699895"
    }
  }
  ```

* ### webhookSubscriptionDelete reference

[Open in GraphiQL](http://localhost:3457/graphiql?query=mutation%20webhookSubscriptionDelete\(%24id%3A%20ID!\)%20%7B%0A%20%20webhookSubscriptionDelete\(id%3A%20%24id\)%20%7B%0A%20%20%20%20userErrors%20%7B%0A%20%20%20%20%20%20field%0A%20%20%20%20%20%20message%0A%20%20%20%20%7D%0A%20%20%20%20deletedWebhookSubscriptionId%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22id%22%3A%20%22gid%3A%2F%2Fshopify%2FWebhookSubscription%2F525699895%22%0A%7D)

```javascript
import { authenticate } from "../shopify.server";


export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation webhookSubscriptionDelete($id: ID!) {
    webhookSubscriptionDelete(id: $id) {
      userErrors {
        field
        message
      }
      deletedWebhookSubscriptionId
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/WebhookSubscription/525699895"
    },
  },
  );
  const json = await response.json();
  return json.data;
}
```

##### GQL

```
mutation webhookSubscriptionDelete($id: ID!) {
  webhookSubscriptionDelete(id: $id) {
    userErrors {
      field
      message
    }
    deletedWebhookSubscriptionId
  }
}
```

##### cURL

```
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation webhookSubscriptionDelete($id: ID!) { webhookSubscriptionDelete(id: $id) { userErrors { field message } deletedWebhookSubscriptionId } }",
 "variables": {
    "id": "gid://shopify/WebhookSubscription/525699895"
  }
}'
```

##### React Router

```
import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation webhookSubscriptionDelete($id: ID!) {
    webhookSubscriptionDelete(id: $id) {
      userErrors {
        field
        message
      }
      deletedWebhookSubscriptionId
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/WebhookSubscription/525699895"
    },
  },
  );
  const json = await response.json();
  return json.data;
}
```

##### Node.js

```
const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation webhookSubscriptionDelete($id: ID!) {
      webhookSubscriptionDelete(id: $id) {
        userErrors {
          field
          message
        }
        deletedWebhookSubscriptionId
      }
    }`,
    "variables": {
        "id": "gid://shopify/WebhookSubscription/525699895"
    },
  },
});
```

##### Ruby

```
session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation webhookSubscriptionDelete($id: ID!) {
    webhookSubscriptionDelete(id: $id) {
      userErrors {
        field
        message
      }
      deletedWebhookSubscriptionId
    }
  }
QUERY

variables = {
  "id": "gid://shopify/WebhookSubscription/525699895"
}

response = client.query(query: query, variables: variables)
```

## Input variables

JSON

```json
{
  "id": "gid://shopify/WebhookSubscription/525699895"
}
```

## Response

JSON

```json
{
  "webhookSubscriptionDelete": {
    "userErrors": [],
    "deletedWebhookSubscriptionId": "gid://shopify/WebhookSubscription/525699895"
  }
}
```