---
updatedAt: 2026-10-01T11:46:10.000Z
agentTools:
  projectIndex: https://partner-docs.gupshup.io/llms.txt
---

# Update App Subscription

This API endpoint enables partners to update configuration of a specific webhook subscription by its unique subscription ID. This allows for granular modifications to individual subscriptions without affecting other webhooks or recreating the subscription. Common use cases include updating webhook URLs, changing event modes, modifying metadata, or toggling subscription status.

## Request Parameters

<Table align={["left","left","left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Key
      </th>

      <th>
        Description
      </th>

      <th>
        Value
      </th>

      <th>
        Data type
      </th>

      <th>
        Required/Optional
      </th>

      <th>
        Constraints
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Authorization
      </td>

      <td>
        Access Token for the application
      </td>

      <td>
        `{{PARTNER_APP_TOKEN}}`
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>
        Should be a valid Partner App Access Token
      </td>
    </tr>

    <tr>
      <td>
        appId
      </td>

      <td>
        App ID to fetch the access token
      </td>

      <td>
        `{{APP_ID}}`
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>
        - The Id should be a valid app Id of Gupshup. - The App must be associated with the account that owns the PARTNER_APP_TOKEN being used
      </td>
    </tr>

    <tr>
      <td>
        SUBSCRIPTION_ID
      </td>

      <td>

      </td>

      <td>
        2xxxx
      </td>

      <td>
        String
      </td>

      <td>
        Required
      </td>

      <td>
        The identifier for the subscription to updated.
      </td>
    </tr>

    <tr>
      <td>
        [modes](https://partner-docs.gupshup.io/reference/setsubscription-api-v3#/modes)
      </td>

      <td>
        Stages in subscription processing
      </td>

      <td>
        \<MODES>
      </td>

      <td>
        String
      </td>

      <td>

      </td>

      <td>
        - Should be one of the following : NONE, READ, DELIVERED, SENT, DELETED, OTHERS - for version 3 TEMPLATE, ACCOUNT, COPY **are not supported**
      </td>
    </tr>

    <tr>
      <td>
        tag
      </td>

      <td>
        Name tag for URL
      </td>

      <td>
        \<name_tag_for_url>
      </td>

      <td>
        String
      </td>

      <td>
        Optional
      </td>

      <td>
        tag must be unique for each app
      </td>
    </tr>

    <tr>
      <td>
        url
      </td>

      <td>
        Callback URL
      </td>

      <td>
        \<callback_url>
      </td>

      <td>
        String
      </td>

      <td>
        Optional
      </td>

      <td>
        Should be valid URL
      </td>
    </tr>

    <tr>
      <td>
        version
      </td>

      <td>
        Version
      </td>

      <td>
        \<version>
      </td>

      <td>
        Integer
      </td>

      <td>
        Optional
      </td>

      <td>
        Should be one of the following : 2,3
      </td>
    </tr>

    <tr>
      <td>
        doCheck
      </td>

      <td>
        For bypassing URL check
      </td>

      <td>
        \<for_bypassing_url_check>
      </td>

      <td>
        Boolean
      </td>

      <td>
        Optional
      </td>

      <td>
        Should be a boolean value : true/false
      </td>
    </tr>

    <tr>
      <td>
        active
      </td>

      <td>
        active status of subscription
      </td>

      <td>
        \<true/false>
      </td>

      <td>
        Boolean
      </td>

      <td>
        Optional
      </td>

      <td>
        Should be a boolean value : true/false
      </td>
    </tr>

    <tr>
      <td>
        meta
      </td>

      <td>
        meta json string (meta json key and value

        will be passed to the subscription URL as headers , users can set custom headers for the URL which can be used for authentication)
      </td>

      <td>
        `{"X-Gupshup-Webhook-Secret":"xxxxxxxxxxxxxxxxx"}`
      </td>

      <td>
        String
      </td>

      <td>
        Optional
      </td>

      <td>

      </td>
    </tr>
  </tbody>
</Table>

## Sample Request

```curl
curl --location --request PUT 'https://partner.gupshup.io/partner/app/{{APP_ID}}/subscription/{{SUBSCRIPTION_ID}}' \
--header 'Authorization: {{PARTNER_APP_TOKEN}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'url=<callback_url>' \
--data-urlencode 'tag=<name_tag_for_url>' \
--data-urlencode 'version=<Version>' \
--data-urlencode 'modes=<MODES>' \
--data-urlencode 'doCheck=<for_bypassing_url_check>' \
--data-urlencode 'active=<true/false>' \
--data-urlencode 'meta={"X-Gupshup-Webhook-Secret":"xxxxxxxxxxxxxxxxx"}'
```

## Sample Response

```
{
  "status" : "success",
  "subscription" : {
    "active" : true,
    "appId" : "657c0203-0b4d-4ba1-bbf5-a679cfa35a16",
    "createdOn" : 1739862125507,
    "id" : "32595",
    "latencyBucket" : "lt_1_s",
    "mode" : 1025,
    "modes" : [ "SENT", "ENQUEUED" ],
    "modifiedOn" : 1739870558358,
    "showOnUI" : false,
    "tag" : "V33i4",
    "url" : "https://01hqjda5pbywgv7xw5e9ckd5e800-51132d4cc32709e9078d.requestinspector.com",
    "version" : 2,
    "meta" : "{\"X-Gupshup-Webhook-Secret\":\"xxxxxxxxxxxxxxxxx\"}"
  }
}
```

## Status Codes

<br />

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Status Code
      </th>

      <th>
        Response
      </th>

      <th>
        Comments
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **Success**
      </td>

      <td>

      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        200
      </td>

      <td>
        \{

        "status" : "success","subscription" :\{"active" : true,
        "appId" : "657c0203-0b4d-4ba1-bbf5-a679cfa35a16",
        "createdOn" : 1739862125507,
        "id" : "32595",
        "latencyBucket" : "lt_1_s",
        "mode" : 1025,
        "modes" : \["SENT", "ENQUEUED"],
        "modifiedOn" : 1739870558358,
        "showOnUI" : false,
        "tag" : "V33i4",
        "url" : "[https://01hqjda5pbywgv7xw5e9ckd5e800-51132d4cc32709e9078d.requestinspector.com](https://01hqjda5pbywgv7xw5e9ckd5e800-51132d4cc32709e9078d.requestinspector.com)",
        "version" : 2,
        "meta" : "{\"X-Gupshup-Webhook-Secret\":\"xxxxxxxxxxxxxxxxx\"}"
        \}
        \}
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        **Error**
      </td>

      <td>

      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        \{

        "status": "error","message": "API key is not associated with partner"\}
      </td>

      <td>
        when API key not found on partner DB
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        \{

        "status": "error","message": "Subscription Does Not Exist"\}
      </td>

      <td>
        When a subscription does not exist with the provided subcriptionId
      </td>
    </tr>

    <tr>
      <td>
        401
      </td>

      <td>
        \{

        "status": "error","message": "Authentication Failed"\}
      </td>

      <td>
        When authentication fails
      </td>
    </tr>

    <tr>
      <td>
        403
      </td>

      <td>
        \{

        "status": "error","message": "Not Subscription Owner"\}
      </td>

      <td>
        When the requested subscription is not associated with the provided appId
      </td>
    </tr>

    <tr>
      <td>
        429
      </td>

      <td>
        \{

        "status": "error","message": "Too Many Requests"\}
      </td>

      <td>

      </td>
    </tr>
  </tbody>
</Table>

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Update Specific App Subscription",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://partner.gupshup.io"
    }
  ],
  "paths": {
    "/partner/app/{appId}/subscription/{subscriptionId}": {
      "put": {
        "tags": [
          "default"
        ],
        "summary": "Update App Subscription",
        "requestBody": {
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Optional",
                    "example": "<callback_url>"
                  },
                  "tag": {
                    "type": "string",
                    "description": "Optional",
                    "example": "<name_tag_for_url>"
                  },
                  "version": {
                    "type": "integer",
                    "description": "Optional",
                    "example": "<Version>"
                  },
                  "modes": {
                    "type": "string",
                    "description": "Optional",
                    "example": "<MODES>"
                  },
                  "doCheck": {
                    "type": "boolean",
                    "description": "Optional",
                    "example": "<for_bypassing_url_check>"
                  },
                  "active": {
                    "type": "boolean",
                    "description": "Optional",
                    "example": "<true/false>"
                  },
                  "meta": {
                    "type": "string",
                    "description": "Optional",
                    "example": "{\"X-Gupshup-Webhook-Secret\":\"xxxxxxxxxxxxxxxxx\"}"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "required": true,
            "example": "sk_3454991ea7724926b8ce6fbfe5e5xxxx"
          },
          {
            "name": "appId",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true,
            "example": "657c0203-xxxx-xxxx-bbf5-a679cfa35a16"
          },
          {
            "name": "subscriptionId",
            "in": "path",
            "schema": {
              "type": "integer"
            },
            "required": true,
            "example": "3xx95"
          }
        ],
        "responses": {
          "200": {
            "$ref": "#/components/responses/200"
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "example": "Too Many Requests"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Internal error occured"
                    },
                    "status": {
                      "type": "string",
                      "example": "error"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "This API endpoint enables partners to update configuration of a specific webhook subscription by its unique subscription ID. This allows for granular modifications to individual subscriptions without affecting other webhooks or recreating the subscription. Common use cases include updating webhook URLs, changing event modes, modifying metadata, or toggling subscription status."
      }
    }
  },
  "components": {
    "responses": {
      "200": {
        "description": "Successful response",
        "content": {
          "application/json": {
            "example": {
              "status": "success",
              "subscription": {
                "active": true,
                "appId": "657c0203-xxxx-xxxx-bbf5-a679cfa35a16",
                "createdOn": 1739862125507,
                "id": "3xx95",
                "latencyBucket": "lt_1_s",
                "mode": 1025,
                "modes": [
                  "SENT",
                  "ENQUEUED"
                ],
                "modifiedOn": 1739870558358,
                "showOnUI": false,
                "tag": "V33i4",
                "url": "https://01hqjda5pbywgv7xw5e9ckd5e800-51132d4cc32709e9078d.requestinspector.com",
                "version": 2,
                "meta": "{\"X-Gupshup-Webhook-Secret\":\"xxxxxxxxxxxxxxxxx\"}"
              }
            }
          }
        }
      },
      "400": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "example": {
              "status": "error",
              "message": "Subscription Does Not Exist"
            }
          }
        }
      },
      "403": {
        "description": "Forbidden",
        "content": {
          "application/json": {
            "example": {
              "status": "error",
              "message": "Not Subscription Owner"
            }
          }
        }
      }
    }
  }
}
```