OpenAPI SpecificationJSON
API Reference

Hook Template

Hook template is a definition of hook in Rossum extension store.

Hook template variables

You can use variable substitution in Hook Templates. To use it, surround an available variable like so {{magic_variable}} anywhere in the request body. If the variable is available, it will be replaced. If the variable is not available, response will return 500.

Currently available Hook Template variables:

Variable
api_url
webhook_base_domain
webhook_domain_prefix

Hook template

Attribute
Type
Description
id*
read-only
integer

ID of the hook template.

type*
"webhook" | "function"

Hook type.

Default: "webhook"
name*
string

Name of the hook template.

url*
read-only
URL

URL of the hook template.

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: {}
config*
object

Configuration of the hook.

test*
object

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

Default: {}
description*
string

Hook description text.

extension_source*
string

Import source of the extension. For more, see Extension sources.

Default: "rossum_store"
settings*
object

Specific settings that will be included in the payload when executing the hook.

Default: {}
settings_schema*
object | null

JSON schema for settings field, specifying the JSON structure of this field.

Default: null
secrets_schema*
object | null

JSON schema for secrets field, specifying the JSON structure of this field.

Default: null
guide*
string

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.

settings_description*
list[object]

Contains description for settings.

Default: []
name
string

Name of settings attribute.

description
string

Description of settings attribute.

tooltip
string

Tooltip for the attribute.

store_description*
string

Description of hook displayed in Rossum store.

external_url*
string

External URL to be called (relates to webhook type).

use_token_owner*
boolean

Whether the hook should use token owner.

Default: false
install_action*
"copy" | "request_access"

Whether the hook is added directly via application (copy) or on customer's request (request_access).

Default: "copy"
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: 7200Default: null
order*
integer

Hook templates can be ordered or grouped by this parameter.

Default: 0

List hook templates

GET api / v1 / hook_templates

Retrieve all hook template objects.

GET
/api/v1/hook_templates
curl -X GET "https://example.rossum.app/api/v1/hook_templates"
{
  "pagination": {
    "next": null,
    "previous": null
  },
  "results": [
    {
      "id": 1,
      "type": "function",
      "name": "Document sorting",
      "url": "https://example.rossum.app/api/v1/hook_templates/1",
      "events": [
        "annotation_status.changed"
      ],
      "sideload": [
        "queues"
      ],
      "metadata": {
        "some_key": "some_value"
      },
      "config": {
        "runtime": "nodejs22.x",
        "code": "exports.rossum_hook_request_handler = () => {\nconst messages = [{\"type\": \"info\", \"content\": \"Yup!\"}];\nconst operations = [];\nreturn {\nmessages,\noperations\n};\n};",
        "schedule": {
          "cron": "*/10 * * * *"
        }
      },
      "test": {},
      "description": "Automatically sort documents into specific queues based on document type (i.e. invoice, bill, PO etc.), POs, vendor, total amount, due date, product or locale.",
      "extension_source": "rossum_store",
      "settings": {},
      "settings_schema": null,
      "secrets_schema": null,
      "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",
      "settings_description": [],
      "store_description": "<p>Automatically sort documents into specific queues based on document type (i.e. invoice, bill, PO etc.), POs, vendor, total amount, due date, product or locale.</p>",
      "external_url": "",
      "use_token_owner": true,
      "install_action": "copy",
      "token_lifetime_s": null,
      "order": 0
    }
  ]
}
{
  "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_template]
id*
read-only
integer

ID of the hook template.

type*
"webhook" | "function"

Hook type.

Default: "webhook"
name*
string

Name of the hook template.

url*
read-only
URL

URL of the hook template.

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: {}
config*
object

Configuration of the hook.

test*
object

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

Default: {}
description*
string

Hook description text.

extension_source*
string

Import source of the extension. For more, see Extension sources.

Default: "rossum_store"
settings*
object

Specific settings that will be included in the payload when executing the hook.

Default: {}
settings_schema*
object | null

JSON schema for settings field, specifying the JSON structure of this field.

Default: null
secrets_schema*
object | null

JSON schema for secrets field, specifying the JSON structure of this field.

Default: null
guide*
string

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.

settings_description*
list[object]

Contains description for settings.

Default: []
name
string

Name of settings attribute.

description
string

Description of settings attribute.

tooltip
string

Tooltip for the attribute.

store_description*
string

Description of hook displayed in Rossum store.

external_url*
string

External URL to be called (relates to webhook type).

use_token_owner*
boolean

Whether the hook should use token owner.

Default: false
install_action*
"copy" | "request_access"

Whether the hook is added directly via application (copy) or on customer's request (request_access).

Default: "copy"
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: 7200Default: null
order*
integer

Hook templates can be ordered or grouped by this parameter.

Default: 0
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

Retrieve hook template

GET api / v1 / hook_templates / {hookTemplateID}

Get a hook template object.

GET
/api/v1/hook_templates/{hookTemplateID}
curl -X GET "https://example.rossum.app/api/v1/hook_templates/0"
{
  "id": 1,
  "type": "function",
  "name": "Document sorting",
  "url": "https://example.rossum.app/api/v1/hook_templates/1",
  "events": [
    "annotation_status.changed"
  ],
  "sideload": [
    "queues"
  ],
  "metadata": {
    "some_key": "some_value"
  },
  "config": {
    "runtime": "nodejs22.x",
    "code": "exports.rossum_hook_request_handler = () => {\nconst messages = [{\"type\": \"info\", \"content\": \"Yup!\"}];\nconst operations = [];\nreturn {\nmessages,\noperations\n};\n};",
    "schedule": {
      "cron": "*/10 * * * *"
    }
  },
  "test": {},
  "description": "Automatically sort documents into specific queues based on document type (i.e. invoice, bill, PO etc.), POs, vendor, total amount, due date, product or locale.",
  "extension_source": "rossum_store",
  "settings": {},
  "settings_schema": null,
  "secrets_schema": null,
  "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",
  "settings_description": [],
  "store_description": "<p>Automatically sort documents into specific queues based on document type (i.e. invoice, bill, PO etc.), POs, vendor, total amount, due date, product or locale.</p>",
  "external_url": "",
  "use_token_owner": true,
  "install_action": "copy",
  "token_lifetime_s": null,
  "order": 0
}
{
  "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
id*
read-only
integer

ID of the hook template.

type*
"webhook" | "function"

Hook type.

Default: "webhook"
name*
string

Name of the hook template.

url*
read-only
URL

URL of the hook template.

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: {}
config*
object

Configuration of the hook.

test*
object

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

Default: {}
description*
string

Hook description text.

extension_source*
string

Import source of the extension. For more, see Extension sources.

Default: "rossum_store"
settings*
object

Specific settings that will be included in the payload when executing the hook.

Default: {}
settings_schema*
object | null

JSON schema for settings field, specifying the JSON structure of this field.

Default: null
secrets_schema*
object | null

JSON schema for secrets field, specifying the JSON structure of this field.

Default: null
guide*
string

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.

settings_description*
list[object]

Contains description for settings.

Default: []
name
string

Name of settings attribute.

description
string

Description of settings attribute.

tooltip
string

Tooltip for the attribute.

store_description*
string

Description of hook displayed in Rossum store.

external_url*
string

External URL to be called (relates to webhook type).

use_token_owner*
boolean

Whether the hook should use token owner.

Default: false
install_action*
"copy" | "request_access"

Whether the hook is added directly via application (copy) or on customer's request (request_access).

Default: "copy"
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: 7200Default: null
order*
integer

Hook templates can be ordered or grouped by this parameter.

Default: 0
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

GETList hook call logsdepr

Previous Page

GETList hook templates

Next Page