OpenAPI SpecificationJSON
API Reference

Hook

A hook is an extension of Rossum that is notified when specific event occurs. A hook object is used to configure what endpoint or function is executed and when. For an overview of other extension options see Extensions

Hook

Attribute
Type
Description
id*
read-only
integer

ID of the hook.

type*
string
name*
string

Name of the hook.

url*
read-only
URL

URL of the hook.

queues*
list[URL]

List of queues that use hook object.

run_after*
list[URL]

List of all hooks that has to be executed before running this hook.

active*
boolean

If set to true the hook is notified.

events*
list[string]

List of events, when the hook should be notified. For the list of events see Webhook events.

sideload*
list[string]

List of related objects that should be included in hook request. For the list of possible sideloads see Webhook events.

Default: []
metadata*
object

Client data. May be used to store e.g. external system object IDs. See Metadata for more details.

Default: {}
token_owner
URL

URL of a user object. If present, an API access token is generated for this user and sent to the hook. Users with organization group admin cannot be set as token_owner. If null, token is not generated.

token_lifetime_s
integer | null

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.

min: 0, max: 7200
test*
object

Input saved for hook testing purposes, see Test a hook.

Default: {}
description
string | null

Hook description text.

extension_source*
"custom" | "rossum_store"

Import source of the extension.

Default: "custom"
settings*
object

Specific settings that will be included in the payload when executing the hook. Field is validated with json schema stored in settings_schema field.

Default: {}
settings_schema
object | null

JSON schema for settings field validation.

secrets
write-only
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)

Default: {}
secrets_schema*
object

JSON schema for secrets field validation.

Default: {"type":"object","additionalProperties":{"type":"string"}}
guide
string | null

Description how to use the extension.

read_more_url
URL

URL address leading to more info page.

extension_image_url
URL

URL address of extension picture.

hook_template
URL

URL of the hook template used to create the hook.

created_by
read-only
URL

URL of the hook creator. Might be null for hooks created before April 2025.

created_at
read-only
datetime

Date of hook creation. Might be null for hooks created before April 2025.

modified_by*
read-only
URL

User that last modified the object.

modified_at*
read-only
datetime

Timestamp of last modification.

config
object

Configuration for webhook hooks.

url
URL

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.

insecure_ssl
boolean

Disable SSL certificate verification (only use for testing purposes).

Default: false
client_ssl_certificate
string | null

Client SSL certificate used to authenticate requests. Must be PEM encoded.

client_ssl_key
write-only
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.

Default: false
schedule
object

Specific configuration for hooks of invocation.scheduled event and action interval. See schedule.

Default: {}
cron
string

Used to set interval with cron expression 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).

min: 0, max: 60Default: 30
retry_count
integer

Number of times the webhook call is retried in case of failure. For non-interactive webhooks only (min=0, max=4).

min: 0, max: 4Default: 4
max_polling_time_s
integer

The maximum polling time in seconds for 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.

min: 1, max: 3600Default: 300
retry_after_polling_failure
boolean

If set to true, the original webhook call is retried in case the polling fails. See the 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.

Default: true
app
deprecated
object | null

(deprecated) (optional) Configuration of the app.

payload_logging_enabled
boolean

(optional) If set to False, hook payload is omitted from hook logs feature accessible via UI.

Default: false
retry_on_any_non_2xx
boolean

(optional) Disabling this option results in retrying only on these response statuses: [408, 429, 500, 502, 503, 504].

Default: false
id*
read-only
integer

ID of the hook.

type*
string
name*
string

Name of the hook.

url*
read-only
URL

URL of the hook.

queues*
list[URL]

List of queues that use hook object.

run_after*
list[URL]

List of all hooks that has to be executed before running this hook.

active*
boolean

If set to true the hook is notified.

events*
list[string]

List of events, when the hook should be notified. For the list of events see Webhook events.

sideload*
list[string]

List of related objects that should be included in hook request. For the list of possible sideloads see Webhook events.

Default: []
metadata*
object

Client data. May be used to store e.g. external system object IDs. See Metadata for more details.

Default: {}
token_owner
URL

URL of a user object. If present, an API access token is generated for this user and sent to the hook. Users with organization group admin cannot be set as token_owner. If null, token is not generated.

token_lifetime_s
integer | null

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.

min: 0, max: 7200
test*
object

Input saved for hook testing purposes, see Test a hook.

Default: {}
description
string | null

Hook description text.

extension_source*
"custom" | "rossum_store"

Import source of the extension.

Default: "custom"
settings*
object

Specific settings that will be included in the payload when executing the hook. Field is validated with json schema stored in settings_schema field.

Default: {}
settings_schema
object | null

JSON schema for settings field validation.

secrets
write-only
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)

Default: {}
secrets_schema*
object

JSON schema for secrets field validation.

Default: {"type":"object","additionalProperties":{"type":"string"}}
guide
string | null

Description how to use the extension.

read_more_url
URL

URL address leading to more info page.

extension_image_url
URL

URL address of extension picture.

hook_template
URL

URL of the hook template used to create the hook.

created_by
read-only
URL

URL of the hook creator. Might be null for hooks created before April 2025.

created_at
read-only
datetime

Date of hook creation. Might be null for hooks created before April 2025.

modified_by*
read-only
URL

User that last modified the object.

modified_at*
read-only
datetime

Timestamp of last modification.

config
object

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
read-only
"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"

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)
Default: "default"
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.

Default: false
schedule
object

Specific configuration for hooks of invocation.scheduled event and action interval. See schedule.

Default: {}
cron
string

Used to set interval with cron expression 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).

min: 0, max: 60Default: 30
memory_size_mb
integer

Function memory limit (min=128, max=256). The limit can be increased upon request.

min: 128, max: 256Default: 256
retry_count
integer

Number of times the function call is retried in case of failure. For non-interactive functions only (min=0, max=4).

min: 0, max: 4Default: 4
app
deprecated
object | null

(deprecated) (optional) Configuration of the app.

payload_logging_enabled
boolean

(optional) If set to False, hook payload is omitted from hook logs feature accessible via UI.

Default: false

List hooks

GET api / v1 / hooks

Retrieve all hook objects.

GET
/api/v1/hooks
curl -X GET "https://example.rossum.app/api/v1/hooks?type=webhook&active=true&config_url=https%3A%2F%2Fmyq.east-west-trading.com&config_app_url=https%3A%2F%2Fmyq.east-west-trading.com&extension_source=custom&events=annotation_status.changed&search=Hook+Foo"
{
  "pagination": {
    "next": null,
    "previous": null
  },
  "results": [
    {
      "id": 1500,
      "type": "webhook",
      "name": "Change of Status",
      "url": "https://example.rossum.app/api/v1/hooks/1500",
      "queues": [
        "https://example.rossum.app/api/v1/queues/8199",
        "https://example.rossum.app/api/v1/queues/8191"
      ],
      "run_after": [],
      "active": true,
      "events": [
        "annotation_status.changed"
      ],
      "sideload": [
        "queues"
      ],
      "metadata": {
        "some_key": "some_value"
      },
      "token_owner": "https://example.rossum.app/api/v1/users/2",
      "token_lifetime_s": 1000,
      "test": {
        "saved_input": {}
      },
      "description": "This hook does...",
      "extension_source": "custom",
      "settings": {},
      "settings_schema": {
        "type": "object",
        "properties": {}
      },
      "secrets": {},
      "secrets_schema": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        }
      },
      "guide": "Here we explain how the extension should be used.",
      "read_more_url": "https://github.com/rossumai/simple-vendor-matching-webhook-python",
      "extension_image_url": "https://rossum.ai/wp-content/themes/rossum/static/img/logo.svg",
      "hook_template": "https://example.rossum.app/api/v1/hook_templates/998877",
      "created_by": "https://example.rossum.app/api/v1/users/2",
      "created_at": "2020-01-01T09:05:50.213451Z",
      "modified_by": "https://example.rossum.app/api/v1/users/10775",
      "modified_at": "2021-04-26T10:08:03.856648Z",
      "config": {
        "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
        "secret": "secret-token",
        "insecure_ssl": false,
        "client_ssl_certificate": "-----BEGIN CERTIFICATE-----\n...",
        "client_ssl_key": "-----BEGIN PRIVATE KEY-----\n...",
        "private": false,
        "schedule": {},
        "timeout_s": 30,
        "retry_count": 4,
        "max_polling_time_s": 300,
        "retry_after_polling_failure": true,
        "app": {
          "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
          "settings": {},
          "display_mode": "drawer"
        },
        "payload_logging_enabled": false,
        "retry_on_any_non_2xx": false
      }
    }
  ]
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Response

200OK

OK

Attribute
Type
Description
pagination*
pagination
next
URL

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
URL

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*
list[hook]
id*
read-only
integer

ID of the hook.

type*
string
name*
string

Name of the hook.

url*
read-only
URL

URL of the hook.

queues*
list[URL]

List of queues that use hook object.

run_after*
list[URL]

List of all hooks that has to be executed before running this hook.

active*
boolean

If set to true the hook is notified.

events*
list[string]

List of events, when the hook should be notified. For the list of events see Webhook events.

sideload*
list[string]

List of related objects that should be included in hook request. For the list of possible sideloads see Webhook events.

Default: []
metadata*
object

Client data. May be used to store e.g. external system object IDs. See Metadata for more details.

Default: {}
token_owner
URL

URL of a user object. If present, an API access token is generated for this user and sent to the hook. Users with organization group admin cannot be set as token_owner. If null, token is not generated.

token_lifetime_s
integer | null

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.

min: 0, max: 7200
test*
object

Input saved for hook testing purposes, see Test a hook.

Default: {}
description
string | null

Hook description text.

extension_source*
"custom" | "rossum_store"

Import source of the extension.

Default: "custom"
settings*
object

Specific settings that will be included in the payload when executing the hook. Field is validated with json schema stored in settings_schema field.

Default: {}
settings_schema
object | null

JSON schema for settings field validation.

secrets_schema*
object

JSON schema for secrets field validation.

Default: {"type":"object","additionalProperties":{"type":"string"}}
guide
string | null

Description how to use the extension.

read_more_url
URL

URL address leading to more info page.

extension_image_url
URL

URL address of extension picture.

hook_template
URL

URL of the hook template used to create the hook.

created_by
read-only
URL

URL of the hook creator. Might be null for hooks created before April 2025.

created_at
read-only
datetime

Date of hook creation. Might be null for hooks created before April 2025.

modified_by*
read-only
URL

User that last modified the object.

modified_at*
read-only
datetime

Timestamp of last modification.

config
object

Configuration for webhook hooks.

url
URL

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.

insecure_ssl
boolean

Disable SSL certificate verification (only use for testing purposes).

Default: false
client_ssl_certificate
string | null

Client SSL certificate used to authenticate requests. Must be PEM encoded.

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.

Default: false
schedule
object

Specific configuration for hooks of invocation.scheduled event and action interval. See schedule.

Default: {}
cron
string

Used to set interval with cron expression 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).

min: 0, max: 60Default: 30
retry_count
integer

Number of times the webhook call is retried in case of failure. For non-interactive webhooks only (min=0, max=4).

min: 0, max: 4Default: 4
max_polling_time_s
integer

The maximum polling time in seconds for 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.

min: 1, max: 3600Default: 300
retry_after_polling_failure
boolean

If set to true, the original webhook call is retried in case the polling fails. See the 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.

Default: true
app
deprecated
object | null

(deprecated) (optional) Configuration of the app.

payload_logging_enabled
boolean

(optional) If set to False, hook payload is omitted from hook logs feature accessible via UI.

Default: false
retry_on_any_non_2xx
boolean

(optional) Disabling this option results in retrying only on these response statuses: [408, 429, 500, 502, 503, 504].

Default: false
id*
read-only
integer

ID of the hook.

type*
string
name*
string

Name of the hook.

url*
read-only
URL

URL of the hook.

queues*
list[URL]

List of queues that use hook object.

run_after*
list[URL]

List of all hooks that has to be executed before running this hook.

active*
boolean

If set to true the hook is notified.

events*
list[string]

List of events, when the hook should be notified. For the list of events see Webhook events.

sideload*
list[string]

List of related objects that should be included in hook request. For the list of possible sideloads see Webhook events.

Default: []
metadata*
object

Client data. May be used to store e.g. external system object IDs. See Metadata for more details.

Default: {}
token_owner
URL

URL of a user object. If present, an API access token is generated for this user and sent to the hook. Users with organization group admin cannot be set as token_owner. If null, token is not generated.

token_lifetime_s
integer | null

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.

min: 0, max: 7200
test*
object

Input saved for hook testing purposes, see Test a hook.

Default: {}
description
string | null

Hook description text.

extension_source*
"custom" | "rossum_store"

Import source of the extension.

Default: "custom"
settings*
object

Specific settings that will be included in the payload when executing the hook. Field is validated with json schema stored in settings_schema field.

Default: {}
settings_schema
object | null

JSON schema for settings field validation.

secrets_schema*
object

JSON schema for secrets field validation.

Default: {"type":"object","additionalProperties":{"type":"string"}}
guide
string | null

Description how to use the extension.

read_more_url
URL

URL address leading to more info page.

extension_image_url
URL

URL address of extension picture.

hook_template
URL

URL of the hook template used to create the hook.

created_by
read-only
URL

URL of the hook creator. Might be null for hooks created before April 2025.

created_at
read-only
datetime

Date of hook creation. Might be null for hooks created before April 2025.

modified_by*
read-only
URL

User that last modified the object.

modified_at*
read-only
datetime

Timestamp of last modification.

config
object

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
read-only
"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"

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)
Default: "default"
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.

Default: false
schedule
object

Specific configuration for hooks of invocation.scheduled event and action interval. See schedule.

Default: {}
cron
string

Used to set interval with cron expression 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).

min: 0, max: 60Default: 30
memory_size_mb
integer

Function memory limit (min=128, max=256). The limit can be increased upon request.

min: 128, max: 256Default: 256
retry_count
integer

Number of times the function call is retried in case of failure. For non-interactive functions only (min=0, max=4).

min: 0, max: 4Default: 4
app
deprecated
object | null

(deprecated) (optional) Configuration of the app.

payload_logging_enabled
boolean

(optional) If set to False, hook payload is omitted from hook logs feature accessible via UI.

Default: false
400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Create hook

POST api / v1 / hooks

Create a new hook object.

POST
/api/v1/hooks
curl -X POST "https://example.rossum.app/api/v1/hooks" \  -H "Content-Type: application/json" \  -d '{    "name": "Change of Status",    "events": [      "annotation_status.changed"    ]  }'
{
  "id": 1500,
  "type": "webhook",
  "name": "Change of Status",
  "url": "https://example.rossum.app/api/v1/hooks/1500",
  "queues": [
    "https://example.rossum.app/api/v1/queues/8199",
    "https://example.rossum.app/api/v1/queues/8191"
  ],
  "run_after": [],
  "active": true,
  "events": [
    "annotation_status.changed"
  ],
  "sideload": [
    "queues"
  ],
  "metadata": {
    "some_key": "some_value"
  },
  "token_owner": "https://example.rossum.app/api/v1/users/2",
  "token_lifetime_s": 1000,
  "test": {
    "saved_input": {}
  },
  "description": "This hook does...",
  "extension_source": "custom",
  "settings": {},
  "settings_schema": {
    "type": "object",
    "properties": {}
  },
  "secrets": {},
  "secrets_schema": {
    "type": "object",
    "additionalProperties": {
      "type": "string"
    }
  },
  "guide": "Here we explain how the extension should be used.",
  "read_more_url": "https://github.com/rossumai/simple-vendor-matching-webhook-python",
  "extension_image_url": "https://rossum.ai/wp-content/themes/rossum/static/img/logo.svg",
  "hook_template": "https://example.rossum.app/api/v1/hook_templates/998877",
  "created_by": "https://example.rossum.app/api/v1/users/2",
  "created_at": "2020-01-01T09:05:50.213451Z",
  "modified_by": "https://example.rossum.app/api/v1/users/10775",
  "modified_at": "2021-04-26T10:08:03.856648Z",
  "config": {
    "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
    "secret": "secret-token",
    "insecure_ssl": false,
    "client_ssl_certificate": "-----BEGIN CERTIFICATE-----\n...",
    "client_ssl_key": "-----BEGIN PRIVATE KEY-----\n...",
    "private": false,
    "schedule": {},
    "timeout_s": 30,
    "retry_count": 4,
    "max_polling_time_s": 300,
    "retry_after_polling_failure": true,
    "app": {
      "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
      "settings": {},
      "display_mode": "drawer"
    },
    "payload_logging_enabled": false,
    "retry_on_any_non_2xx": false
  }
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Payload Too Large.",
  "code": "payload_too_large"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Request Body

application/json

bodyobject

Response

201Created

Created

responseobject
400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Retrieve hook

GET api / v1 / hooks / {hookID}

Get a hook object.

GET
/api/v1/hooks/{hookID}
curl -X GET "https://example.rossum.app/api/v1/hooks/1500"
{
  "id": 1500,
  "type": "webhook",
  "name": "Change of Status",
  "url": "https://example.rossum.app/api/v1/hooks/1500",
  "queues": [
    "https://example.rossum.app/api/v1/queues/8199",
    "https://example.rossum.app/api/v1/queues/8191"
  ],
  "run_after": [],
  "active": true,
  "events": [
    "annotation_status.changed"
  ],
  "sideload": [
    "queues"
  ],
  "metadata": {
    "some_key": "some_value"
  },
  "token_owner": "https://example.rossum.app/api/v1/users/2",
  "token_lifetime_s": 1000,
  "test": {
    "saved_input": {}
  },
  "description": "This hook does...",
  "extension_source": "custom",
  "settings": {},
  "settings_schema": {
    "type": "object",
    "properties": {}
  },
  "secrets": {},
  "secrets_schema": {
    "type": "object",
    "additionalProperties": {
      "type": "string"
    }
  },
  "guide": "Here we explain how the extension should be used.",
  "read_more_url": "https://github.com/rossumai/simple-vendor-matching-webhook-python",
  "extension_image_url": "https://rossum.ai/wp-content/themes/rossum/static/img/logo.svg",
  "hook_template": "https://example.rossum.app/api/v1/hook_templates/998877",
  "created_by": "https://example.rossum.app/api/v1/users/2",
  "created_at": "2020-01-01T09:05:50.213451Z",
  "modified_by": "https://example.rossum.app/api/v1/users/10775",
  "modified_at": "2021-04-26T10:08:03.856648Z",
  "config": {
    "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
    "secret": "secret-token",
    "insecure_ssl": false,
    "client_ssl_certificate": "-----BEGIN CERTIFICATE-----\n...",
    "client_ssl_key": "-----BEGIN PRIVATE KEY-----\n...",
    "private": false,
    "schedule": {},
    "timeout_s": 30,
    "retry_count": 4,
    "max_polling_time_s": 300,
    "retry_after_polling_failure": true,
    "app": {
      "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
      "settings": {},
      "display_mode": "drawer"
    },
    "payload_logging_enabled": false,
    "retry_on_any_non_2xx": false
  }
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Response

200OK

OK

responseobject
400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Partial update hook

PATCH api / v1 / hooks / {hookID}

Update part of hook object.

PATCH
/api/v1/hooks/{hookID}
curl -X PATCH "https://example.rossum.app/api/v1/hooks/1500" \  -H "Content-Type: application/json" \  -d '{}'
{
  "id": 1500,
  "type": "webhook",
  "name": "Change of Status",
  "url": "https://example.rossum.app/api/v1/hooks/1500",
  "queues": [
    "https://example.rossum.app/api/v1/queues/8199",
    "https://example.rossum.app/api/v1/queues/8191"
  ],
  "run_after": [],
  "active": true,
  "events": [
    "annotation_status.changed"
  ],
  "sideload": [
    "queues"
  ],
  "metadata": {
    "some_key": "some_value"
  },
  "token_owner": "https://example.rossum.app/api/v1/users/2",
  "token_lifetime_s": 1000,
  "test": {
    "saved_input": {}
  },
  "description": "This hook does...",
  "extension_source": "custom",
  "settings": {},
  "settings_schema": {
    "type": "object",
    "properties": {}
  },
  "secrets": {},
  "secrets_schema": {
    "type": "object",
    "additionalProperties": {
      "type": "string"
    }
  },
  "guide": "Here we explain how the extension should be used.",
  "read_more_url": "https://github.com/rossumai/simple-vendor-matching-webhook-python",
  "extension_image_url": "https://rossum.ai/wp-content/themes/rossum/static/img/logo.svg",
  "hook_template": "https://example.rossum.app/api/v1/hook_templates/998877",
  "created_by": "https://example.rossum.app/api/v1/users/2",
  "created_at": "2020-01-01T09:05:50.213451Z",
  "modified_by": "https://example.rossum.app/api/v1/users/10775",
  "modified_at": "2021-04-26T10:08:03.856648Z",
  "config": {
    "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
    "secret": "secret-token",
    "insecure_ssl": false,
    "client_ssl_certificate": "-----BEGIN CERTIFICATE-----\n...",
    "client_ssl_key": "-----BEGIN PRIVATE KEY-----\n...",
    "private": false,
    "schedule": {},
    "timeout_s": 30,
    "retry_count": 4,
    "max_polling_time_s": 300,
    "retry_after_polling_failure": true,
    "app": {
      "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
      "settings": {},
      "display_mode": "drawer"
    },
    "payload_logging_enabled": false,
    "retry_on_any_non_2xx": false
  }
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Payload Too Large.",
  "code": "payload_too_large"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Request Body

application/json

bodyobject

Response

200OK

OK

responseobject
400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Delete hook

DELETE api / v1 / hooks / {hookID}

Delete hook object.

DELETE
/api/v1/hooks/{hookID}
curl -X DELETE "https://example.rossum.app/api/v1/hooks/1500"
Empty
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Response

204No Content

No Content

No response body.

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Update hook

PUT api / v1 / hooks / {hookID}

Update hook object.

PUT
/api/v1/hooks/{hookID}
curl -X PUT "https://example.rossum.app/api/v1/hooks/1500" \  -H "Content-Type: application/json" \  -d '{    "name": "Change of Status",    "events": [      "annotation_status.changed"    ]  }'
{
  "id": 1500,
  "type": "webhook",
  "name": "Change of Status",
  "url": "https://example.rossum.app/api/v1/hooks/1500",
  "queues": [
    "https://example.rossum.app/api/v1/queues/8199",
    "https://example.rossum.app/api/v1/queues/8191"
  ],
  "run_after": [],
  "active": true,
  "events": [
    "annotation_status.changed"
  ],
  "sideload": [
    "queues"
  ],
  "metadata": {
    "some_key": "some_value"
  },
  "token_owner": "https://example.rossum.app/api/v1/users/2",
  "token_lifetime_s": 1000,
  "test": {
    "saved_input": {}
  },
  "description": "This hook does...",
  "extension_source": "custom",
  "settings": {},
  "settings_schema": {
    "type": "object",
    "properties": {}
  },
  "secrets": {},
  "secrets_schema": {
    "type": "object",
    "additionalProperties": {
      "type": "string"
    }
  },
  "guide": "Here we explain how the extension should be used.",
  "read_more_url": "https://github.com/rossumai/simple-vendor-matching-webhook-python",
  "extension_image_url": "https://rossum.ai/wp-content/themes/rossum/static/img/logo.svg",
  "hook_template": "https://example.rossum.app/api/v1/hook_templates/998877",
  "created_by": "https://example.rossum.app/api/v1/users/2",
  "created_at": "2020-01-01T09:05:50.213451Z",
  "modified_by": "https://example.rossum.app/api/v1/users/10775",
  "modified_at": "2021-04-26T10:08:03.856648Z",
  "config": {
    "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
    "secret": "secret-token",
    "insecure_ssl": false,
    "client_ssl_certificate": "-----BEGIN CERTIFICATE-----\n...",
    "client_ssl_key": "-----BEGIN PRIVATE KEY-----\n...",
    "private": false,
    "schedule": {},
    "timeout_s": 30,
    "retry_count": 4,
    "max_polling_time_s": 300,
    "retry_after_polling_failure": true,
    "app": {
      "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
      "settings": {},
      "display_mode": "drawer"
    },
    "payload_logging_enabled": false,
    "retry_on_any_non_2xx": false
  }
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Payload Too Large.",
  "code": "payload_too_large"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Request Body

application/json

bodyobject

Response

200OK

OK

responseobject
400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Create hook from template

POST api / v1 / hooks / create

Create a new hook object with the option to use a referenced hook template as a base.

POST
/api/v1/hooks/create
curl -X POST "https://example.rossum.app/api/v1/hooks/create" \  -H "Content-Type: application/json" \  -d '{    "name": "Change of Status",    "events": [      "annotation_status.changed"    ]  }'
{
  "id": 1500,
  "type": "webhook",
  "name": "Change of Status",
  "url": "https://example.rossum.app/api/v1/hooks/1500",
  "queues": [
    "https://example.rossum.app/api/v1/queues/8199",
    "https://example.rossum.app/api/v1/queues/8191"
  ],
  "run_after": [],
  "active": true,
  "events": [
    "annotation_status.changed"
  ],
  "sideload": [
    "queues"
  ],
  "metadata": {
    "some_key": "some_value"
  },
  "token_owner": "https://example.rossum.app/api/v1/users/2",
  "token_lifetime_s": 1000,
  "test": {
    "saved_input": {}
  },
  "description": "This hook does...",
  "extension_source": "custom",
  "settings": {},
  "settings_schema": {
    "type": "object",
    "properties": {}
  },
  "secrets": {},
  "secrets_schema": {
    "type": "object",
    "additionalProperties": {
      "type": "string"
    }
  },
  "guide": "Here we explain how the extension should be used.",
  "read_more_url": "https://github.com/rossumai/simple-vendor-matching-webhook-python",
  "extension_image_url": "https://rossum.ai/wp-content/themes/rossum/static/img/logo.svg",
  "hook_template": "https://example.rossum.app/api/v1/hook_templates/998877",
  "created_by": "https://example.rossum.app/api/v1/users/2",
  "created_at": "2020-01-01T09:05:50.213451Z",
  "modified_by": "https://example.rossum.app/api/v1/users/10775",
  "modified_at": "2021-04-26T10:08:03.856648Z",
  "config": {
    "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
    "secret": "secret-token",
    "insecure_ssl": false,
    "client_ssl_certificate": "-----BEGIN CERTIFICATE-----\n...",
    "client_ssl_key": "-----BEGIN PRIVATE KEY-----\n...",
    "private": false,
    "schedule": {},
    "timeout_s": 30,
    "retry_count": 4,
    "max_polling_time_s": 300,
    "retry_after_polling_failure": true,
    "app": {
      "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
      "settings": {},
      "display_mode": "drawer"
    },
    "payload_logging_enabled": false,
    "retry_on_any_non_2xx": false
  }
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Payload Too Large.",
  "code": "payload_too_large"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Request Body

application/json

bodyobject

Response

201Created

Created

responseobject
400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Duplicate hook

POST api / v1 / hooks / {hookID} / duplicate

Duplicate a hook object. hook.queues is not copied by default, but can be copied using the copy_queues option. Duplicated hook is always inactive (hook.active = False).

POST
/api/v1/hooks/{hookID}/duplicate
curl -X POST "https://example.rossum.app/api/v1/hooks/1500/duplicate" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{
  "id": 1500,
  "type": "webhook",
  "name": "Change of Status",
  "url": "https://example.rossum.app/api/v1/hooks/1500",
  "queues": [
    "https://example.rossum.app/api/v1/queues/8199",
    "https://example.rossum.app/api/v1/queues/8191"
  ],
  "run_after": [],
  "active": true,
  "events": [
    "annotation_status.changed"
  ],
  "sideload": [
    "queues"
  ],
  "metadata": {
    "some_key": "some_value"
  },
  "token_owner": "https://example.rossum.app/api/v1/users/2",
  "token_lifetime_s": 1000,
  "test": {
    "saved_input": {}
  },
  "description": "This hook does...",
  "extension_source": "custom",
  "settings": {},
  "settings_schema": {
    "type": "object",
    "properties": {}
  },
  "secrets": {},
  "secrets_schema": {
    "type": "object",
    "additionalProperties": {
      "type": "string"
    }
  },
  "guide": "Here we explain how the extension should be used.",
  "read_more_url": "https://github.com/rossumai/simple-vendor-matching-webhook-python",
  "extension_image_url": "https://rossum.ai/wp-content/themes/rossum/static/img/logo.svg",
  "hook_template": "https://example.rossum.app/api/v1/hook_templates/998877",
  "created_by": "https://example.rossum.app/api/v1/users/2",
  "created_at": "2020-01-01T09:05:50.213451Z",
  "modified_by": "https://example.rossum.app/api/v1/users/10775",
  "modified_at": "2021-04-26T10:08:03.856648Z",
  "config": {
    "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
    "secret": "secret-token",
    "insecure_ssl": false,
    "client_ssl_certificate": "-----BEGIN CERTIFICATE-----\n...",
    "client_ssl_key": "-----BEGIN PRIVATE KEY-----\n...",
    "private": false,
    "schedule": {},
    "timeout_s": 30,
    "retry_count": 4,
    "max_polling_time_s": 300,
    "retry_after_polling_failure": true,
    "app": {
      "url": "https://myq.east-west-trading.com/api/hook1?strict=true",
      "settings": {},
      "display_mode": "drawer"
    },
    "payload_logging_enabled": false,
    "retry_on_any_non_2xx": false
  }
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Payload Too Large.",
  "code": "payload_too_large"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Request Body

application/json

Attribute
Type
Description
name*
string

Name of the duplicated hook.

copy_secrets
boolean

Whether to copy secrets.

Default: false
copy_dependencies
boolean

Whether to copy dependencies. If enabled, this option copies the dependency relations of the original hook. It duplicates the run_after references to preserve which hooks the original hook depended on, and it also updates all hooks that previously depended on the original hook to reference the new duplicated one. This ensures that both dependency directions—"runs after" and "is run after by"—are correctly maintained.

Default: false
copy_queues
boolean

Whether to copy queue assignments from the original hook to the duplicated hook.

Default: false

Response

201Created

Created

responseobject
400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Generate hook payload

POST api / v1 / hooks / {hookID} / generate_payload

Users can use this endpoint to test the hook on a payload of specific events and actions.

The token used for calling the endpoint is returned as rossum_authorization_token regardless of the token_owner of the hook. Values in secrets are redacted for security reasons. The payload for email events from this endpoint may differ from the original hook payload in the file ids, height, width, and format of email addresses in headers.

POST
/api/v1/hooks/{hookID}/generate_payload
curl -X POST "https://example.rossum.app/api/v1/hooks/1500/generate_payload" \  -H "Content-Type: application/json" \  -d '{    "action": "scheduled",    "event": "invocation"  }'
{
  "request_id": "ae7bc8dd-73bd-489b-a3d2-f5514b209591",
  "timestamp": "2020-01-01T00:00:00.000000Z",
  "base_url": "https://example.rossum.app",
  "rossum_authorization_token": "1024873d424a007d8eebff7b3684d283abdf7d0d",
  "hook": "https://example.rossum.app/api/v1/hooks/1500",
  "settings": {
    "example_target_service_type": "SFTP",
    "example_target_hostname": "sftp.elis.rossum.ai"
  },
  "secrets": {
    "username": "[redacted...]",
    "password": "[redacted...]"
  },
  "action": "scheduled",
  "event": "invocation"
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Payload Too Large.",
  "code": "payload_too_large"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Request Body

application/json

Attribute
Type
Description
action*
string

Hook's action.

event*
string

Hook's event.

annotation
URL

URL of related Annotation object. Required for annotation_status and annotation_content events.

previous_status
string

A previous status of the document. See Annotation Lifecycle for a list of supported values. Required for annotation_status and annotation_content events.

status
string

Status of the document. See Annotation Lifecycle for a list of supported values. Required for annotation_status and annotation_content events.

email
URL

URL of the arriving email. Required for email event.

upload
URL

URL of an upload instance. Required for upload event.

Response

200OK

OK

Attribute
Type
Description
request_id
string

Request ID.

timestamp
datetime

Timestamp.

base_url
URL

Base URL.

rossum_authorization_token
string

Authorization token.

hook
URL

Hook URL.

settings
object

Hook settings.

secrets
object

Hook secrets (values redacted).

action
string

Action.

event
string

Event.

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Retrieve secret keys list

GET api / v1 / hooks / {hookID} / secrets_keys

Retrieve all secrets in a list (only keys are retrieved, values are encrypted in DB and aren't possible to obtain via API).

GET
/api/v1/hooks/{hookID}/secrets_keys
curl -X GET "https://example.rossum.app/api/v1/hooks/1500/secrets_keys"
[
  "secret_key1",
  "secret_key2"
]
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Response

200OK

OK

responselist[string]

List of hook secrets keys.

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Test hook

POST api / v1 / hooks / {hookID} / test

Test a hook with custom payload. Test endpoint will return result generated by the specified Hook which would be normally processed by Rossum.

POST
/api/v1/hooks/{hookID}/test
curl -X POST "https://example.rossum.app/api/v1/hooks/1500/test" \  -H "Content-Type: application/json" \  -d '{    "payload": {      "action": "started",      "event": "annotation_content",      "annotation": {},      "document": {},      "settings": {}    }  }'
{
  "response": {
    "messages": [],
    "operations": []
  }
}
{
  "detail": "Bad Request.",
  "code": "bad_request"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Test function is not ready yet"
}
{
  "detail": "Payload Too Large.",
  "code": "payload_too_large"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Request Body

application/json

Attribute
Type
Description
config
object

You can override default configuration of hook being executed. The runtime attribute is required for function hook if custom config is set.

payload*
object

Payload sent to the Hook, please note only supported combination of action and event can be passed.

Response

200OK

OK

Attribute
Type
Description
response
object

Response from the hook.

400Bad Request

Invalid input data.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict - Test function is not ready yet, request should be retried after 10 seconds.

Attribute
Type
Description
detail
string
413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

Trigger manual hook

POST api / v1 / hooks / {hookID} / invoke

Invoke the hook with custom payload. The payload will be added to the standard invocation event hook request and sent to the hook. The hook response is returned in the invocation response payload.

Values for standard json hook response attributes (request_id, action, ...) will NOT be overwritten.

Attribute timeout_s in hook config for this endpoint POST /v1/hooks/{id}/invoke will be overwritten by default value of 30.

POST
/api/v1/hooks/{hookID}/invoke
curl -X POST "https://example.rossum.app/api/v1/hooks/1500/invoke" \  -H "Content-Type: application/json" \  -d '{    "SAP_ID": "1234",    "DB_COLUMN": "SAP"  }'
{}
{
  "detail": "Hook must have proper event and action configuration"
}
{
  "detail": "Invalid token.",
  "code": "authentication_failed"
}
{
  "detail": "Access to the requested resource is forbidden.",
  "code": "access_forbidden"
}
{
  "detail": "Not found.",
  "code": "not_found"
}
{
  "detail": "Conflict.",
  "code": "conflict_status"
}
{
  "detail": "Payload Too Large.",
  "code": "payload_too_large"
}
{
  "detail": "Request was rate limited.",
  "code": "rate_limited",
  "url": "https://rossum.app/api/docs/openapi/guides/overview/#rate-limiting"
}
{
  "detail": "Server error.",
  "code": "error"
}
{
  "detail": "Bad Gateway.",
  "code": "bad_gateway"
}
{
  "detail": "Service Unavailable.",
  "code": "service_unavailable"
}
{
  "detail": "Gateway timeout.",
  "code": "gateway_timeout"
}

Request Body

application/json

bodyobjectrequired

Object with properties to be merged into the invocation payload.

Response

200OK

OK

responseobject

Hook response merged with invocation response payload.

400Bad Request

Bad Request - Not having proper event and action in hook object or non-json response.

Attribute
Type
Description
detail
string
401Unauthorized

The username/password is invalid or token is invalid (e.g. expired).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

403Forbidden

Insufficient permission, missing authentication, invalid CSRF token and similar issue.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

404Not Found

The specified resource was not found.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

409Conflict

Conflict

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

413

Payload too large (especially for files uploaded).

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

429Too Many Requests

Request rate is too high, wait before sending more requests. See Rate Limiting for more details.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

url
read-only
string

Link to the rate limiting documentation

500Internal Server Error

Server failure while processing the request.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

502Bad Gateway

Invalid response from the upstream server.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

503Service Unavailable

We're temporarily offline for maintenance. Please try again later.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

504

Upstream server could not complete the request in time.

Attribute
Type
Description
detail
read-only
string

Detail of the error

code
read-only
string

Code of the error

GETRetrieve generic engine schema

Previous Page

GETList hooks

Next Page