---
title: "List hooks"
method: GET
path: "/api/v1/hooks"
tags: ["Hook"]
---

# List hooks

`GET /api/v1/hooks`

Retrieve all hook objects.

## Query parameters

- `page_size` integer
- `cursor` string
- `id` integer[]
- `name` string
- `type` 'webhook' | 'function'
- `queue` integer[]
- `active` boolean
- `config_url` string
- `config_app_url` string
- `extension_source` 'custom' | 'rossum_store'
- `events` string
- `search` string
- `ordering` 'id' | '-id' | 'name' | '-name' | 'type' | '-type' | 'active' | '-active' | 'config_url' | '-config_url' | 'config_app_url' | '-config_app_url' | 'events' | '-events'

## Response `200`

OK

- object
  - `pagination` Pagination, required
    - `next` string, uri, nullable — URL for the next page of results. Contains an opaque signed `cursor` query parameter. Use this URL directly to fetch the next page — do not attempt to construct or modify the cursor value.
    - `previous` string, uri, nullable — URL for the previous page of results. Contains an opaque signed `cursor` query parameter. Use this URL directly to fetch the previous page — do not attempt to construct or modify the cursor value.
  - `results` Hook[], required
    - union
      - object
        - `id` integer, required — ID of the hook.
        - `type` 'webhook', required — Hook type.
        - `name` string, required — Name of the hook.
        - `url` string, uri, required — URL of the hook.
        - `queues` string[], required — List of queues that use hook object.
        - `run_after` string[], required — List of all hooks that has to be executed before running this hook.
        - `integration_credentials` string[], required — List of [integration credentials](/api/integration-credential) used by the hook. Only credentials of the same organization may be attached.
        - `active` boolean, required — If set to `true` the hook is notified.
        - `events` string[], required — List of events, when the hook should be notified. For the list of events see [Webhook events](/guides/extensions#webhook-extension).
        - `sideload` string[], required — List of related objects that should be included in hook request. For the list of possible sideloads see [Webhook events](/guides/extensions#webhook-extension).
        - `metadata` Metadata, required — Client data. May be used to store e.g. external system object IDs. See [Metadata](/guides/overview#metadata) for more details.
        - `token_owner` string, uri, nullable — URL of a user object. If present, an API access token is generated for this user and [sent to the hook](/guides/extensions#webhook-extension). Users with organization group admin cannot be set as token_owner. If `null`, token is not generated.
        - `token_lifetime_s` integer, nullable — Lifetime number of seconds for `rossum_authorization_token` (min=0, max=7200). This setting will ensure the token will be valid after hook response is returned. If `null`, default lifetime of `600` is used.
        - `test` object, required — Input saved for hook testing purposes, see [Test a hook](/api/hook#test-hook).
        - `description` string, nullable — Hook description text.
        - `extension_source` 'custom' | 'rossum_store', required — Import source of the extension.
        - `settings` object, required — Specific settings that will be included in the payload when executing the hook. Field is validated with json schema stored in `settings_schema` field.
        - `settings_schema` object, nullable — JSON schema for `settings` field validation.
        - `secrets` object — Specific secrets that are stored securely encrypted. The values are merged into the hook execution payload. Field is validated with json schema stored in `secrets_schema` field. (write only)
        - `secrets_schema` object, required — JSON schema for `secrets` field validation.
        - `guide` string, nullable — Description how to use the extension.
        - `read_more_url` string, uri, nullable — URL address leading to more info page.
        - `extension_image_url` string, uri, nullable — URL address of extension picture.
        - `hook_template` string, uri, nullable — URL of the hook template used to create the hook.
        - `created_by` string, uri, nullable — URL of the hook creator. Might be `null` for hooks created before April 2025.
        - `created_at` string, date-time, nullable — Date of hook creation. Might be `null` for hooks created before April 2025.
        - `modified_by` string, uri, nullable, required — User that last modified the object.
        - `modified_at` string, date-time, nullable, required — Timestamp of last modification.
        - `config` WebhookConfig — Configuration for webhook hooks.
          - `url` string, uri — URL of the webhook endpoint to call.
          - `secret` string — (optional) If set, it is used to create a hash signature with each payload. For more information see [Validating payloads from Rossum](#validating-payloads-from-rossum).
          - `insecure_ssl` boolean — Disable SSL certificate verification (only use for testing purposes).
          - `client_ssl_certificate` string, nullable — Client SSL certificate used to authenticate requests. Must be PEM encoded.
          - `client_ssl_key` string — Client SSL key (write only). Must be PEM encoded. Key may not be encrypted.
          - `private` boolean — (optional) If set, the `url` and `secret` values become hidden and immutable once the hook is created. The value of this flag cannot be changed to `false` once set.
          - `schedule` object — Specific configuration for hooks of invocation.scheduled event and action interval. See [schedule](#schedule-object).
            - `cron` string — Used to set interval with [cron expression](https://crontab.guru/) in UTC timezone. Cron object interval can't be shorter than every 10 minutes.
          - `timeout_s` integer — Webhook call timeout in seconds. For non-interactive webhooks only (min=0, max=60).
          - `retry_count` integer — Number of times the webhook call is retried in case of failure. For non-interactive webhooks only (min=0, max=4).
          - `max_polling_time_s` integer — The maximum polling time in seconds for [asynchronous webhooks](#asynchronous-webhooks) (min=1, max=3600). It is possible to configure this value only for `upload.created`, `invocation.scheduled`, and `annotation_content.export` events. For other non-interactive events the default value is used.
          - `retry_after_polling_failure` boolean — If set to `true`, the original webhook call is retried in case the polling fails. See the [asynchronous webhooks](#asynchronous-webhooks) section for more details. Possible to configure only for `upload.created`, `invocation.scheduled`, and `annotation_content.export` events. For other non-interactive events the default value is used.
          - `app` object, nullable — (deprecated) (optional) Configuration of the app.
            - `url` string, uri, required — URL of the app that will be embedded in Rossum UI.
            - `settings` object — Settings of the app that can be used for further customization of configuration app (such as UI schema etc.).
            - `display_mode` 'drawer' | 'fullscreen' — Display mode of the app. `drawer` opens a drawer with embedded URL, `fullscreen` opens an embedded URL in full-screen overlay.
          - `payload_logging_enabled` boolean — (optional) If set to False, hook payload is omitted from hook logs feature accessible via UI.
          - `retry_on_any_non_2xx` boolean — (optional) Disabling this option results in retrying only on these response statuses: [408, 429, 500, 502, 503, 504].
      - object
        - `id` integer, required — ID of the hook.
        - `type` 'function', required — Hook type.
        - `name` string, required — Name of the hook.
        - `url` string, uri, required — URL of the hook.
        - `queues` string[], required — List of queues that use hook object.
        - `run_after` string[], required — List of all hooks that has to be executed before running this hook.
        - `integration_credentials` string[], required — List of [integration credentials](/api/integration-credential) used by the hook. Only credentials of the same organization may be attached.
        - `active` boolean, required — If set to `true` the hook is notified.
        - `events` string[], required — List of events, when the hook should be notified. For the list of events see [Webhook events](/guides/extensions#webhook-extension).
        - `sideload` string[], required — List of related objects that should be included in hook request. For the list of possible sideloads see [Webhook events](/guides/extensions#webhook-extension).
        - `metadata` Metadata, required — Client data. May be used to store e.g. external system object IDs. See [Metadata](/guides/overview#metadata) for more details.
        - `token_owner` string, uri, nullable — URL of a user object. If present, an API access token is generated for this user and [sent to the hook](/guides/extensions#webhook-extension). Users with organization group admin cannot be set as token_owner. If `null`, token is not generated.
        - `token_lifetime_s` integer, nullable — Lifetime number of seconds for `rossum_authorization_token` (min=0, max=7200). This setting will ensure the token will be valid after hook response is returned. If `null`, default lifetime of `600` is used.
        - `test` object, required — Input saved for hook testing purposes, see [Test a hook](/api/hook#test-hook).
        - `description` string, nullable — Hook description text.
        - `extension_source` 'custom' | 'rossum_store', required — Import source of the extension.
        - `settings` object, required — Specific settings that will be included in the payload when executing the hook. Field is validated with json schema stored in `settings_schema` field.
        - `settings_schema` object, nullable — JSON schema for `settings` field validation.
        - `secrets` object — Specific secrets that are stored securely encrypted. The values are merged into the hook execution payload. Field is validated with json schema stored in `secrets_schema` field. (write only)
        - `secrets_schema` object, required — JSON schema for `secrets` field validation.
        - `guide` string, nullable — Description how to use the extension.
        - `read_more_url` string, uri, nullable — URL address leading to more info page.
        - `extension_image_url` string, uri, nullable — URL address of extension picture.
        - `hook_template` string, uri, nullable — URL of the hook template used to create the hook.
        - `created_by` string, uri, nullable — URL of the hook creator. Might be `null` for hooks created before April 2025.
        - `created_at` string, date-time, nullable — Date of hook creation. Might be `null` for hooks created before April 2025.
        - `modified_by` string, uri, nullable, required — User that last modified the object.
        - `modified_at` string, date-time, nullable, required — Timestamp of last modification.
        - `config` FunctionConfig — Configuration for function hooks.
          - `runtime` 'nodejs22.x' | 'python3.12' — Runtime used to execute code. Allowed values: `nodejs22.x` or `python3.12`.
          - `code` string — String-serialized source code to be executed.
          - `status` 'ready' | 'pending' | 'failed' — Status indicates whether the function is ready to be invoked or modified. Possible values are `ready`, `pending` or `failed`. While the state is `pending`, invocations and other API actions that operate on the function return status 400. It is recommended to resave function for `failed` state. (Function hooks only)
          - `third_party_library_pack` 'null' | 'default', nullable — Set of libraries to be included in execution environment of the function. For Python 3.12: * `null` (only standard library), * `default` (rossum, requests, jmespath, xmltodict, pydantic, pandas, httpx, boto3, botocore) For Node.js 22: * `null` (built-in modules only), * `default` (node-fetch, https-proxy-agent, lodash)
          - `private` boolean — (optional) If set, the `runtime`, `code` and `third_party_library_pack` values become hidden and immutable once the hook is created. The value of this flag cannot be changed to `false` once set.
          - `schedule` object — Specific configuration for hooks of invocation.scheduled event and action interval. See [schedule](#schedule-object).
            - `cron` string — Used to set interval with [cron expression](https://crontab.guru/) in UTC timezone. Cron object interval can't be shorter than every 10 minutes.
          - `timeout_s` integer — Function call timeout in seconds. For non-interactive functions only (min=0, max=60).
          - `memory_size_mb` integer — Function memory limit (min=128, max=256). The limit can be increased upon request.
          - `retry_count` integer — Number of times the function call is retried in case of failure. For non-interactive functions only (min=0, max=4).
          - `app` object, nullable — (deprecated) (optional) Configuration of the app.
            - `url` string, uri — URL of the app that will be embedded in Rossum UI.
            - `settings` object — Settings of the app that can be used for further customization of configuration app (such as UI schema etc.).
            - `display_mode` 'drawer' | 'fullscreen' — Display mode of the app. `drawer` opens a drawer with embedded URL, `fullscreen` opens an embedded URL in full-screen overlay.
          - `payload_logging_enabled` boolean — (optional) If set to False, hook payload is omitted from hook logs feature accessible via UI.

## Other responses

- `400` — Invalid input data.
- `401` — The username/password is invalid or token is invalid (e.g. expired).
- `403` — Insufficient permission, missing authentication, invalid CSRF token and similar issue.
- `404` — The specified resource was not found.
- `409` — Conflict
- `429` — Request rate is too high, wait before sending more requests. See [Rate Limiting](/guides/overview#rate-limiting) for more details.
- `500` — Server failure while processing the request.
- `502` — Invalid response from the upstream server.
- `503` — We're temporarily offline for maintenance. Please try again later.
- `504` — Upstream server could not complete the request in time.

---

[API](https://skmtc.dev/rossum/apis/rossum-api.md) · [All operations](https://skmtc.dev/rossum/apis/rossum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rossum/rossum-api/revisions/f1b5a910991d/schema)