> ## Documentation Index > Fetch the complete documentation index at: https://docs.usertick.com/llms.txt > Use this file to discover all available pages before exploring further. # Subscribe a URL > A REST hook subscribe: signed deliveries of one event (see webhooks for each one's body), on one survey or every survey, narrowed by the filters the event takes. Event workflow.step instead binds the URL to a workflow's Zapier step (workflowId and stepId, from GET /workflows/zapier-steps): the workflow sends a response to it when a run reaches the step, in the body of the event that started the run. One live subscription per step (409 WH-005-010); an app's member needs the permission to manage workflows. 201 with the whsec_ secret (shown only here); 200 when this credential already subscribed the URL (brought to these settings). Deliveries carry responses, so it needs responses:read too. Scopes: webhooks:write, responses:read. ## OpenAPI ````yaml api-reference/openapi.json POST /webhooks/subscribe openapi: 3.1.0 info: title: Usertick Public API version: 1.0.0 description: >- The Usertick REST API v1: responses, surveys, metrics and webhook subscriptions of one organization. **Authentication.** Send an API key (Settings, Developers, API keys; utk_...) or an app's OAuth access token (uto_...) as Authorization: Bearer. X-Api-Key works for clients that cannot set Authorization. Each endpoint lists the scopes it needs. API keys work on Pro plans and up, and apps such as Zapier on Starter plans and up. **Format.** Plain JSON resources; times are RFC 3339 in UTC with milliseconds (2026-09-30T10:00:00.000Z). Lists are { data, nextCursor }: limit is 1 to 100 (default 25, out of range is 400), and nextCursor goes back as cursor until it is null. A page starts strictly after the last row of the page before, so a row deleted or renamed in between never ends a list early. **Errors.** Every error is { statusCode, success: false, code, message, data }, plus errors: [{ field, code, message }] for invalid fields. Switch on code (x-error-codes lists them all); messages may change. **Rate limits.** 120 requests a minute per credential and 600 per organization, as token buckets. An answer to an authenticated request has X-RateLimit-Limit, -Remaining and -Reset (seconds until the budget is full) for the credential, and X-RateLimit-Org-* for the organization, except a 429 over the credential's budget, which has the credential's only. Over a budget is 429 with Retry-After. A 401 carries no X-RateLimit headers, and neither does a 429 GEN-429-001 from the per-address limit (3,000 requests a minute per client address, checked before the credential). **Idempotency.** Every POST takes an Idempotency-Key header: the same key and request within 24 hours get the first answer again. **Versioning.** Within /v1 changes are additive only: new endpoints, new optional parameters, new fields (ignore fields you do not know). Anything that will go away is announced at least six months ahead with Deprecation and Sunset headers on its answers. **Webhooks.** Every delivery is { id, type, createdAt, data }, signed per Standard Webhooks (see webhooks). data is the Response resource, with change on response.status_changed and response.classification_corrected; on theme.spiking it is the spike. Every answer carries X-Request-Id. contact: name: Usertick support url: https://usertick.com/support servers: - url: https://app.usertick.com/api/public/v1 description: Production security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: Account - name: Responses - name: Surveys - name: Metrics - name: Webhooks paths: /webhooks/subscribe: post: tags: - Webhooks summary: Subscribe a URL description: >- A REST hook subscribe: signed deliveries of one event (see webhooks for each one's body), on one survey or every survey, narrowed by the filters the event takes. Event workflow.step instead binds the URL to a workflow's Zapier step (workflowId and stepId, from GET /workflows/zapier-steps): the workflow sends a response to it when a run reaches the step, in the body of the event that started the run. One live subscription per step (409 WH-005-010); an app's member needs the permission to manage workflows. 201 with the whsec_ secret (shown only here); 200 when this credential already subscribed the URL (brought to these settings). Deliveries carry responses, so it needs responses:read too. Scopes: webhooks:write, responses:read. operationId: subscribeWebhook parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubscribeBody' responses: '200': description: Already subscribed. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' X-RateLimit-Org-Limit: $ref: '#/components/headers/XRateLimitOrgLimit' X-RateLimit-Org-Remaining: $ref: '#/components/headers/XRateLimitOrgRemaining' X-RateLimit-Org-Reset: $ref: '#/components/headers/XRateLimitOrgReset' content: application/json: schema: $ref: '#/components/schemas/Subscription' '201': description: Created. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' X-RateLimit-Org-Limit: $ref: '#/components/headers/XRateLimitOrgLimit' X-RateLimit-Org-Remaining: $ref: '#/components/headers/XRateLimitOrgRemaining' X-RateLimit-Org-Reset: $ref: '#/components/headers/XRateLimitOrgReset' content: application/json: schema: $ref: '#/components/schemas/Subscription' '400': description: >- The request isn't valid. Codes: APK-006-001, APK-006-002, APK-006-003, APK-006-004, APK-006-010, APK-006-011, APK-006-008, APK-006-009, APK-006-013, WH-005-001, WH-005-005, PUB-002-001. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-006-001: $ref: '#/components/examples/APK-006-001' APK-006-002: $ref: '#/components/examples/APK-006-002' APK-006-003: $ref: '#/components/examples/APK-006-003' APK-006-004: $ref: '#/components/examples/APK-006-004' APK-006-010: $ref: '#/components/examples/APK-006-010' APK-006-011: $ref: '#/components/examples/APK-006-011' APK-006-008: $ref: '#/components/examples/APK-006-008' APK-006-009: $ref: '#/components/examples/APK-006-009' APK-006-013: $ref: '#/components/examples/APK-006-013' WH-005-001: $ref: '#/components/examples/WH-005-001' WH-005-005: $ref: '#/components/examples/WH-005-005' PUB-002-001: $ref: '#/components/examples/PUB-002-001' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: 'The resource couldn''t be found. Codes: APK-006-005, APK-006-014.' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-006-005: $ref: '#/components/examples/APK-006-005' APK-006-014: $ref: '#/components/examples/APK-006-014' '409': description: >- The request conflicts with the current state. Codes: WH-005-006, WH-005-008, WH-005-010, PUB-002-002, PUB-002-003. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' examples: WH-005-006: $ref: '#/components/examples/WH-005-006' WH-005-008: $ref: '#/components/examples/WH-005-008' WH-005-010: $ref: '#/components/examples/WH-005-010' PUB-002-002: $ref: '#/components/examples/PUB-002-002' PUB-002-003: $ref: '#/components/examples/PUB-002-003' '413': $ref: '#/components/responses/PayloadTooLarge' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: IdempotencyKey: name: Idempotency-Key in: header description: >- Any 1 to 255 printable ASCII characters, without a space at either end. The answer to the first request with a key is kept for 24 hours per credential: the same request again gets it back (Idempotent-Replayed: true), another request with the key is 409 PUB-002-002, and while the first still runs 409 PUB-002-003. A server error is not kept, and a request that never answered frees its key after 2 minutes: a retry with the key then runs again. required: false schema: type: string maxLength: 255 schemas: SubscribeBody: type: object properties: targetUrl: type: string format: uri minLength: 8 maxLength: 2048 event: type: string enum: - response.created - response.analyzed - response.status_changed - response.classification_corrected - response.urgent - theme.spiking - workflow.step surveyId: type: - string - 'null' format: uuid filters: oneOf: - $ref: '#/components/schemas/SubscriptionFilters' - type: 'null' workflowId: type: string description: >- workflow.step only, with stepId: the workflow (GET /workflows/zapier-steps lists its Zapier steps). format: uuid stepId: type: string description: 'workflow.step only: the Zapier step''s id in the workflow.' maxLength: 32 required: - targetUrl - event additionalProperties: false examples: - targetUrl: https://hooks.example.com/usertick event: response.analyzed filters: types: - bug urgencies: - high - targetUrl: https://hooks.example.com/urgent event: response.urgent filters: themes: - 44444444-4444-4444-8444-444444444444 - targetUrl: https://hooks.zapier.com/hooks/standard/1/abc event: workflow.step workflowId: 9c3d4e5f-6071-4c8d-8e9f-1a2b3c4d5e6f stepId: s_k3v9q2 Subscription: type: object properties: id: type: string format: uuid targetUrl: type: string format: uri event: type: string enum: - response.created - response.analyzed - response.status_changed - response.classification_corrected - response.urgent - theme.spiking - workflow.step surveyId: type: - string - 'null' format: uuid filters: oneOf: - $ref: '#/components/schemas/SubscriptionFilters' - type: 'null' secret: type: string description: The whsec_ signing secret. createdAt: type: string format: date-time examples: - '2026-09-30T10:00:00.000Z' workflowId: type: - string - 'null' description: >- workflow.step only: the workflow whose Zapier step sends to it; null for the other events. format: uuid stepId: type: - string - 'null' description: >- workflow.step only: that step's id in the workflow; null for the other events. required: - id - targetUrl - event - surveyId - filters - secret - createdAt - workflowId - stepId additionalProperties: false Error: type: object properties: statusCode: type: integer description: The HTTP status, again. success: type: boolean description: Always false. code: type: string description: >- What went wrong, stable across versions (see x-error-codes). For invalid fields, the first field's code. examples: - PUB-001-001 message: type: - string - 'null' description: The code's message in English (US); null for a code without one. data: description: Extra context for some errors; null otherwise. errors: type: array items: $ref: '#/components/schemas/FieldError' description: >- Every invalid field, in the order of the request's parameters. Only on a 400 about fields. required: - statusCode - success - code - message - data description: >- Every error answer. Success answers are the plain resource or list instead. additionalProperties: false examples: - statusCode: 400 success: false code: PUB-001-001 message: The limit must be between 1 and 100. data: null errors: - field: limit code: PUB-001-001 message: The limit must be between 1 and 100. - field: sort code: PUB-001-005 message: The sort order must be asc or desc. SubscriptionFilters: type: object properties: types: type: array items: type: string enum: - bug - idea - complaint - question - praise urgencies: type: array items: type: string enum: - high - medium - low themes: type: array items: type: string format: uuid description: Theme ids (GET /themes), at most 5,000. maxItems: 5000 required: [] description: >- What each event takes: response.analyzed, response.status_changed and response.classification_corrected all three; response.urgent types and themes; theme.spiking themes; response.created none (400 APK-006-002 otherwise). A response matches when any answer has one of the types, its urgency is one of the bands, and any answer has one of the themes. additionalProperties: false FieldError: type: object properties: field: type: string description: >- The query parameter, or the body property (camelCase, dotted when nested). code: type: string message: type: - string - 'null' required: - field - code - message additionalProperties: false headers: XRequestId: description: >- This answer's id (req_ and 32 hex characters), also in the logs. Quote it to support. schema: type: string XRateLimitLimit: description: The credential's requests per minute. schema: type: integer XRateLimitRemaining: description: What is left of it now. schema: type: integer XRateLimitReset: description: >- Seconds until the credential's budget is full again (the bucket refills continuously). schema: type: integer XRateLimitOrgLimit: description: Every credential of the organization together, per minute. schema: type: integer XRateLimitOrgRemaining: description: What is left of the organization's budget. schema: type: integer XRateLimitOrgReset: description: Seconds until the organization's budget is full again. schema: type: integer RetryAfter: description: Seconds to wait before trying again. schema: type: integer examples: APK-006-001: summary: >- The event isn't recognized. Use response.created, response.analyzed, response.status_changed, response.classification_corrected, response.urgent, theme.spiking or workflow.step. value: statusCode: 400 success: false code: APK-006-001 message: >- The event isn't recognized. Use response.created, response.analyzed, response.status_changed, response.classification_corrected, response.urgent, theme.spiking or workflow.step. data: null APK-006-002: summary: >- This event doesn't accept these filters. response.created accepts none, response.urgent doesn't accept urgency, and theme.spiking accepts only themes. value: statusCode: 400 success: false code: APK-006-002 message: >- This event doesn't accept these filters. response.created accepts none, response.urgent doesn't accept urgency, and theme.spiking accepts only themes. data: null APK-006-003: summary: >- The feedback type isn't recognized. Use bug, idea, complaint, question or praise. The type filter of GET /responses also takes none. value: statusCode: 400 success: false code: APK-006-003 message: >- The feedback type isn't recognized. Use bug, idea, complaint, question or praise. The type filter of GET /responses also takes none. data: null APK-006-004: summary: The urgency isn't recognized. Use high, medium or low. value: statusCode: 400 success: false code: APK-006-004 message: The urgency isn't recognized. Use high, medium or low. data: null APK-006-010: summary: The theme isn't recognized. Use theme IDs from GET /themes. value: statusCode: 400 success: false code: APK-006-010 message: The theme isn't recognized. Use theme IDs from GET /themes. data: null APK-006-011: summary: Filter by at most 5,000 themes. value: statusCode: 400 success: false code: APK-006-011 message: Filter by at most 5,000 themes. data: null APK-006-008: summary: Send the https URL that should receive the deliveries. value: statusCode: 400 success: false code: APK-006-008 message: Send the https URL that should receive the deliveries. data: null APK-006-009: summary: The target URL must be 8 to 2048 characters. value: statusCode: 400 success: false code: APK-006-009 message: The target URL must be 8 to 2048 characters. data: null APK-006-013: summary: >- workflow.step needs both workflowId and stepId, and the other events take neither. value: statusCode: 400 success: false code: APK-006-013 message: >- workflow.step needs both workflowId and stepId, and the other events take neither. data: null WH-005-001: summary: This URL isn't allowed. Use a public https address. value: statusCode: 400 success: false code: WH-005-001 message: This URL isn't allowed. Use a public https address. data: null WH-005-005: summary: Webhook URLs must start with https://. value: statusCode: 400 success: false code: WH-005-005 message: Webhook URLs must start with https://. data: null PUB-002-001: summary: >- Send an Idempotency-Key of 1 to 255 printable ASCII characters, without a space at either end. value: statusCode: 400 success: false code: PUB-002-001 message: >- Send an Idempotency-Key of 1 to 255 printable ASCII characters, without a space at either end. data: null APK-006-005: summary: The survey couldn't be found. value: statusCode: 404 success: false code: APK-006-005 message: The survey couldn't be found. data: null APK-006-014: summary: >- The workflow step couldn't be found. Add a Zapier step to the workflow, or pick one from GET /workflows/zapier-steps. value: statusCode: 404 success: false code: APK-006-014 message: >- The workflow step couldn't be found. Add a Zapier step to the workflow, or pick one from GET /workflows/zapier-steps. data: null WH-005-006: summary: Another webhook already uses this URL. Subscribe with a different URL. value: statusCode: 409 success: false code: WH-005-006 message: Another webhook already uses this URL. Subscribe with a different URL. data: null WH-005-008: summary: >- This API key, app or organization has reached its limit of webhook subscriptions. Unsubscribe one, then try again. value: statusCode: 409 success: false code: WH-005-008 message: >- This API key, app or organization has reached its limit of webhook subscriptions. Unsubscribe one, then try again. data: null WH-005-010: summary: >- Another Zap already receives this workflow step. Turn that Zap off first. value: statusCode: 409 success: false code: WH-005-010 message: >- Another Zap already receives this workflow step. Turn that Zap off first. data: null PUB-002-002: summary: >- This Idempotency-Key was used with a different request. Use a new key for a new request. value: statusCode: 409 success: false code: PUB-002-002 message: >- This Idempotency-Key was used with a different request. Use a new key for a new request. data: null PUB-002-003: summary: >- A request with this Idempotency-Key is still running. Try again in a moment. value: statusCode: 409 success: false code: PUB-002-003 message: >- A request with this Idempotency-Key is still running. Try again in a moment. data: null APK-004-001: summary: Send an API key or an access token in the Authorization header. value: statusCode: 401 success: false code: APK-004-001 message: Send an API key or an access token in the Authorization header. data: null APK-004-002: summary: >- The API key or access token is invalid, expired or revoked. Connect again with a valid one. value: statusCode: 401 success: false code: APK-004-002 message: >- The API key or access token is invalid, expired or revoked. Connect again with a valid one. data: null APK-004-004: summary: >- This API key or app doesn't have permission for this request. Grant it the required scope. value: statusCode: 403 success: false code: APK-004-004 message: >- This API key or app doesn't have permission for this request. Grant it the required scope. data: null APK-004-005: summary: >- Your plan doesn't include API keys or the MCP server. To use them, upgrade to Pro or higher. value: statusCode: 403 success: false code: APK-004-005 message: >- Your plan doesn't include API keys or the MCP server. To use them, upgrade to Pro or higher. data: null APK-004-008: summary: >- Your plan doesn't include apps that use the API, such as Zapier. To use them, upgrade to Starter or higher. value: statusCode: 403 success: false code: APK-004-008 message: >- Your plan doesn't include apps that use the API, such as Zapier. To use them, upgrade to Starter or higher. data: null AUTHZ-001-002: summary: Your role doesn't have the required permission. value: statusCode: 403 success: false code: AUTHZ-001-002 message: Your role doesn't have the required permission. data: null GEN-000-413: summary: The request is too large. Send less data or a smaller file. value: statusCode: 413 success: false code: GEN-000-413 message: The request is too large. Send less data or a smaller file. data: null APK-004-003: summary: This API key or app sent too many requests. Wait a minute and try again. value: statusCode: 429 success: false code: APK-004-003 message: >- This API key or app sent too many requests. Wait a minute and try again. data: null APK-004-006: summary: >- Your organization sent too many API requests. Wait a minute and try again. value: statusCode: 429 success: false code: APK-004-006 message: >- Your organization sent too many API requests. Wait a minute and try again. data: null GEN-429-001: summary: Too many requests were sent. Wait a minute and try again. value: statusCode: 429 success: false code: GEN-429-001 message: Too many requests were sent. Wait a minute and try again. data: null responses: Unauthorized: description: >- No credential, or one that is invalid, expired or revoked. Codes: APK-004-001, APK-004-002. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-004-001: $ref: '#/components/examples/APK-004-001' APK-004-002: $ref: '#/components/examples/APK-004-002' Forbidden: description: >- The credential lacks a scope this endpoint needs, the plan does not include the API (API keys on Pro and up, apps such as Zapier on Starter and up), or an app's member lacks the permission. Codes: APK-004-004, APK-004-005, APK-004-008, AUTHZ-001-002. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-004-004: $ref: '#/components/examples/APK-004-004' APK-004-005: $ref: '#/components/examples/APK-004-005' APK-004-008: $ref: '#/components/examples/APK-004-008' AUTHZ-001-002: $ref: '#/components/examples/AUTHZ-001-002' PayloadTooLarge: description: 'The body is over 64 KB. Codes: GEN-000-413.' headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: GEN-000-413: $ref: '#/components/examples/GEN-000-413' TooManyRequests: description: >- Over the credential's or the organization's budget, or over the per-address limit that is checked before the credential (GEN-429-001, without X-RateLimit headers). Codes: APK-004-003, APK-004-006, GEN-429-001. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' examples: APK-004-003: $ref: '#/components/examples/APK-004-003' APK-004-006: $ref: '#/components/examples/APK-004-006' GEN-429-001: $ref: '#/components/examples/GEN-429-001' securitySchemes: bearerAuth: type: http scheme: bearer description: An API key (utk_live_...) or an app's OAuth access token (uto_...). apiKeyHeader: type: apiKey in: header name: X-Api-Key description: The API key, for clients that cannot send Authorization. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.