---
updatedAt: 2026-03-06T12:20:29.000Z
---

Fetch the complete documentation index at: https://developer.productboard.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# List webhook subscriptions

Returns all webhook subscriptions for the workspace. Returns up to 100 items per page by default.

Paginated using cursor-based pagination. Follow `links.next` in the response to fetch the next page.
When `links.next` is `null`, you have reached the last page.

**OAuth2 isolation**: OAuth2 access tokens only see subscriptions created by the same OAuth2 application.
Public API access tokens see all workspace subscriptions.


# OpenAPI definition

```json
{
  "openapi": "3.1.1",
  "info": {
    "title": "Webhooks",
    "description": "Manages webhook subscriptions. Subscribe to entity change events and receive\nreal-time notifications at your endpoint.\n",
    "version": "2.0.0",
    "contact": {
      "name": "Productboard Support",
      "url": "https://support.productboard.com",
      "email": "support@productboard.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.productboard.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.productboard.com/v2",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    },
    {
      "OAuth2": [
        "entities:read",
        "write:entities",
        "entities:delete"
      ]
    }
  ],
  "tags": [
    {
      "name": "webhooks",
      "description": "Operations for managing webhook subscriptions."
    }
  ],
  "paths": {
    "/webhooks": {
      "get": {
        "summary": "List webhook subscriptions",
        "description": "Returns all webhook subscriptions for the workspace. Returns up to 100 items per page by default.\n\nPaginated using cursor-based pagination. Follow `links.next` in the response to fetch the next page.\nWhen `links.next` is `null`, you have reached the last page.\n\n**OAuth2 isolation**: OAuth2 access tokens only see subscriptions created by the same OAuth2 application.\nPublic API access tokens see all workspace subscriptions.\n",
        "operationId": "listWebhooks",
        "security": [
          {
            "BearerAuth": [
              "webhooks:read"
            ]
          }
        ],
        "tags": [
          "webhooks"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/PageCursor"
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of webhook subscriptions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookListResponse"
                },
                "example": {
                  "data": [
                    {
                      "id": "550e8400-e29b-41d4-a716-446655440000",
                      "type": "webhook",
                      "createdAt": "2024-01-15T10:30:00.000Z",
                      "fields": {
                        "name": "Feature changes webhook",
                        "events": [
                          {
                            "eventType": "feature.updated"
                          }
                        ],
                        "notification": {
                          "url": "https://example.destination.com/webhooks-handler",
                          "version": 1
                        }
                      },
                      "links": {
                        "self": "https://api.productboard.com/v2/webhooks/550e8400-e29b-41d4-a716-446655440000"
                      }
                    }
                  ],
                  "links": {
                    "next": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestResponse"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedResponse"
          },
          "403": {
            "$ref": "#/components/responses/ForbiddenResponse"
          },
          "408": {
            "$ref": "#/components/responses/RequestTimeoutResponse"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequestsResponse"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerErrorResponse"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "PageCursor": {
        "name": "pageCursor",
        "in": "query",
        "required": false,
        "description": "Cursor for pagination. Use the value from `links.next` to fetch the next page.",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "WebhookType": {
        "type": "string",
        "description": "Resource type identifier for webhook subscriptions.",
        "enum": [
          "webhook"
        ],
        "example": "webhook"
      },
      "WebhookSubscription": {
        "type": "object",
        "description": "A webhook subscription resource.",
        "required": [
          "id",
          "type",
          "createdAt",
          "fields",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true,
            "description": "Unique identifier for this webhook subscription.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "type": {
            "$ref": "#/components/schemas/WebhookType"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "ISO 8601 timestamp when the subscription was created.",
            "example": "2024-01-15T10:30:00.000Z"
          },
          "fields": {
            "$ref": "#/components/schemas/WebhookSubscriptionResponseFields"
          },
          "links": {
            "$ref": "#/components/schemas/WebhookSubscriptionLinks"
          }
        }
      },
      "WebhookListResponse": {
        "type": "object",
        "description": "Response envelope for a paginated list of webhook subscriptions.",
        "required": [
          "data",
          "links"
        ],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookSubscription"
            }
          },
          "links": {
            "$ref": "#/components/schemas/ListLinks"
          }
        }
      },
      "WebhookSubscriptionResponseFields": {
        "type": "object",
        "description": "Domain attributes returned in webhook subscription responses.\nNote: `notification.headers.authorization` is intentionally absent from responses to protect secrets.\n",
        "required": [
          "name",
          "events",
          "notification"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Human-readable label for this subscription.",
            "minLength": 1,
            "maxLength": 255,
            "example": "Feature changes webhook"
          },
          "events": {
            "type": "array",
            "description": "Event types that trigger this subscription.",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/WebhookEvent"
            }
          },
          "notification": {
            "$ref": "#/components/schemas/WebhookNotificationConfigResponse"
          }
        }
      },
      "WebhookSubscriptionLinks": {
        "type": "object",
        "description": "Links for this webhook subscription resource.",
        "required": [
          "self"
        ],
        "properties": {
          "self": {
            "type": "string",
            "format": "uri",
            "description": "URL to retrieve this webhook subscription.",
            "example": "https://api.productboard.com/v2/webhooks/550e8400-e29b-41d4-a716-446655440000"
          }
        }
      },
      "WebhookEvent": {
        "type": "object",
        "required": [
          "eventType"
        ],
        "properties": {
          "eventType": {
            "$ref": "#/components/schemas/WebhookEventType"
          }
        }
      },
      "WebhookEventType": {
        "type": "string",
        "description": "Identifies the type of entity change that triggers a webhook notification.",
        "enum": [
          "feature.created",
          "feature.updated",
          "feature.deleted",
          "component.created",
          "component.updated",
          "product.created",
          "product.updated",
          "release.created",
          "release.updated",
          "release.deleted",
          "feature-release-assignment.updated",
          "hierarchy-entity.custom-field-value.updated",
          "note.created",
          "note.updated",
          "note.deleted",
          "insight.created",
          "insight.deleted",
          "key-result.created",
          "key-result.updated",
          "key-result.deleted",
          "objective.created",
          "objective.updated",
          "objective.deleted",
          "initiative.created",
          "initiative.updated",
          "initiative.deleted"
        ]
      },
      "WebhookNotificationConfigResponse": {
        "type": "object",
        "description": "Notification configuration as returned in responses (secret omitted).",
        "required": [
          "url",
          "version"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 1024,
            "description": "Target URL for webhook notifications.",
            "example": "https://example.destination.com/webhooks-handler"
          },
          "version": {
            "$ref": "#/components/schemas/WebhookPayloadVersion"
          }
        }
      },
      "WebhookPayloadVersion": {
        "type": "integer",
        "description": "Version of the notification payload structure. Currently only `1` is supported.",
        "enum": [
          1
        ],
        "example": 1
      },
      "ListLinks": {
        "type": "object",
        "required": [
          "next"
        ],
        "properties": {
          "next": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ErrorSource": {
        "type": "object",
        "description": "An object containing references to the source of the error. It helps with location of the problematic field or parameter.\n",
        "properties": {
          "pointer": {
            "type": "string",
            "description": "JSON Pointer [RFC6901] to the associated entity in the request document.\n",
            "example": "/data/fields/status"
          },
          "parameter": {
            "type": "string",
            "description": "Query parameter causing the error.\nUsed when the error is related to a query parameter rather than request body.\n",
            "example": "pageCursor"
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Individual error object containing the details and context.\n",
        "required": [
          "code",
          "title",
          "detail"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "A unique, machine-readable and stable code that identifies this error.\nMust be consistent across all services and provide clear categorization.\nFormat: `category.subcategory.specificError`\n",
            "examples": [
              "auth.accessDenied",
              "resource.notFound"
            ]
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem that doesn't change\nfrom occurrence to occurrence of the problem. Should provide immediate\nunderstanding of the error type.\n",
            "maxLength": 255,
            "example": "Missing required field"
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem.\nMay include suggestions for resolution but should not expose sensitive information.\n",
            "maxLength": 1000,
            "example": "Field 'status' is required."
          },
          "source": {
            "$ref": "#/components/schemas/ErrorSource"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "Standard error response structure.\n",
        "required": [
          "id",
          "errors"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "A unique identifier for this specific occurrence of the problem.\nIt carries unique request/response ID which allows client\nand server to reference the exact instance of the error\nin logs or support communication.\n"
          },
          "errors": {
            "type": "array",
            "description": "Array of error objects, multiple errors can be returned.",
            "items": {
              "$ref": "#/components/schemas/Error"
            },
            "minItems": 1
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API token authentication. Use your API token as the value of the Authorization header"
      },
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 authentication. Use this for user-authorized access to Productboard API.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://app.productboard.com/oauth/authorize",
            "tokenUrl": "https://app.productboard.com/oauth/token",
            "scopes": {
              "entities:read": "Read access to entities (features, components, initiatives, etc.)",
              "write:entities": "Write access to create and modify entities",
              "entities:delete": "Delete entities"
            }
          }
        }
      }
    },
    "responses": {
      "BadRequestResponse": {
        "description": "Bad Request - Invalid input format or malformed request",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "schemaInvalid": {
                "summary": "Request does not satisfy schema",
                "value": {
                  "id": "req-1234567890",
                  "errors": [
                    {
                      "code": "request.invalid",
                      "title": "Request schema invalid",
                      "detail": "The request does not satisfy the required schema. Field 'type' is required but was not provided.",
                      "source": {
                        "pointer": "/data/type"
                      }
                    }
                  ]
                }
              },
              "fieldInvalid": {
                "summary": "Invalid field value type",
                "value": {
                  "id": "req-1234567891",
                  "errors": [
                    {
                      "code": "request.invalid",
                      "title": "Request schema invalid",
                      "detail": "Field 'fields/name' must be a string with maximum length of 255 characters, but received a number.",
                      "source": {
                        "pointer": "/data/fields/name"
                      }
                    }
                  ]
                }
              },
              "malformedJson": {
                "summary": "Malformed JSON syntax",
                "value": {
                  "id": "req-1234567892",
                  "errors": [
                    {
                      "code": "request.malformed",
                      "title": "Request malformed",
                      "detail": "The request body contains invalid JSON syntax. Expected ',' or '}' at line 5, column 12."
                    }
                  ]
                }
              },
              "invalidContentType": {
                "summary": "Invalid content type",
                "value": {
                  "id": "req-1234567893",
                  "errors": [
                    {
                      "code": "request.malformed",
                      "title": "Request malformed",
                      "detail": "The Content-Type header must be 'application/json'. Received 'text/plain'."
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "UnauthorizedResponse": {
        "description": "Unauthorized - Missing or invalid authentication credentials",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingCredentials": {
                "summary": "Missing authentication credentials",
                "value": {
                  "id": "req-2234567890",
                  "errors": [
                    {
                      "code": "auth.invalid",
                      "title": "Invalid authentication",
                      "detail": "Authentication credentials are missing."
                    }
                  ]
                }
              },
              "invalidToken": {
                "summary": "Invalid or expired token",
                "value": {
                  "id": "req-2234567891",
                  "errors": [
                    {
                      "code": "auth.invalid",
                      "title": "Invalid authentication",
                      "detail": "The provided authentication credentials are invalid or have expired. Please obtain new credentials and try again."
                    }
                  ]
                }
              },
              "revokedCredentials": {
                "summary": "Revoked credentials",
                "value": {
                  "id": "req-2234567892",
                  "errors": [
                    {
                      "code": "auth.invalid",
                      "title": "Invalid authentication",
                      "detail": "The authentication credentials have been revoked. Please contact your workspace administrator."
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "ForbiddenResponse": {
        "description": "Forbidden - Insufficient permissions",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "permissionDenied": {
                "summary": "Permission denied for resource",
                "value": {
                  "id": "req-3234567890",
                  "errors": [
                    {
                      "code": "auth.accessDenied",
                      "title": "Access denied",
                      "detail": "You do not have permission to perform this operation on the specified resource. Contact your workspace administrator to request access."
                    }
                  ]
                }
              },
              "insufficientScope": {
                "summary": "Insufficient OAuth scopes",
                "value": {
                  "id": "req-3234567891",
                  "errors": [
                    {
                      "code": "auth.accessDenied",
                      "title": "Access denied",
                      "detail": "Your authentication token lacks the required OAuth scopes to perform this operation. Please re-authenticate with the necessary scopes."
                    }
                  ]
                }
              },
              "readOnlyRole": {
                "summary": "Read-only role restriction",
                "value": {
                  "id": "req-3234567892",
                  "errors": [
                    {
                      "code": "auth.accessDenied",
                      "title": "Access denied",
                      "detail": "Your user role does not permit this operation. Please contact your workspace administrator."
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "RequestTimeoutResponse": {
        "description": "Request Timeout - The server did not receive a complete request within the allowed time",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "requestTimeout": {
                "summary": "Request timeout",
                "value": {
                  "id": "req-5234567890",
                  "errors": [
                    {
                      "code": "request.timeout",
                      "title": "Request timeout",
                      "detail": "The request took too long to process and was terminated. Try simplifying your request or try again later."
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "TooManyRequestsResponse": {
        "description": "Too Many Requests - API rate limit exceeded, reduce request frequency and retry after the indicated time",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "rateLimitExceeded": {
                "summary": "Rate limit exceeded",
                "value": {
                  "id": "req-7234567890",
                  "errors": [
                    {
                      "code": "rate.limitExceeded",
                      "title": "Rate limit exceeded",
                      "detail": "You have exceeded the allowed number of API requests. Please wait before making additional requests."
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "InternalServerErrorResponse": {
        "description": "Internal Server Error - An unexpected error occurred on the server, please retry or contact support",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "internalServerError": {
                "summary": "Unexpected server error",
                "value": {
                  "id": "req-8234567890",
                  "errors": [
                    {
                      "code": "internal.serverError",
                      "title": "Internal server error",
                      "detail": "An unexpected error occurred while processing your request. Please try again later. If the problem persists, contact support with the correlation ID."
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "samples-languages": [
      "shell",
      "javascript",
      "ruby"
    ]
  }
}
```