Sink Routes

Corteza allows you to detect incoming HTTP requests via automation scripts — sink routes. Sink routes allow you to implement custom API endpoints to add support for things like webhooks.

Here, we only cover how to setup a sink route. Refer to the Low-Code Platform Developer Guide for details on how to use them.

Generating a Signature

A sink signature is used to authorize incoming HTTP requests to the /sink route.

Sink signatures should be treated as passwords.

A sink signature is generated using the sink signature CLI command.

For example docker-compose exec server corteza-server sink signature returns such an output (the signature will be different):

/system/sink?__sign=187...3D
Sink request constraints:
 - signature should be part of query-string
 - body size is not limited

Refer to the CLI command reference for details on available options (docker-compose exec server corteza-server sink signature -h). The above command creates an unconstrained signature (any request is considered as valid).

The signature can be found at the end of the __sign query parameter.

This signature should be stored somewhere safe as it is required to authenticate any request to the sink route.

Each request to the sink route must specify the sink signature we generated above.

Some services (when implementing the OAuth2 flow) may not allow the use of query parameters. See Unable to Use Query Parameters? to bypass the restriction.

Use the Sink Route

When you need to use the sink route (e.g. you wish to define a webhook), all inbound requests must specify the sink signature generated above. Either in the query parameter or in the path (depending on the provided CLI parameters).

For example:

curl '$BASE_API_URL/system/sink?__sign=$SINK_SIGNATURE' \
  --data-binary '{
    "a": "b"
  }';

Note that when using a custom API base URL (see: HTTP_API_BASE_URL) or you have webapp incorporated into the server (see: HTTP_WEBAPP_ENABLED), the sink url would be prefixed (ie by default per webapp enabled: $BASE_API_URL/api/system/sink?__sign=$SINK_SIGNATURE).

If you can’t use a query parameter to authenticate the request, add the --signature-in-path argument tho the sink signature CLI command.

For example docker-compose exec server corteza-server sink signature --signature-in-path returns such an output (the signature will be different):

/system/sink/ext_mautic/lead/__sign=7a9...==
Sink request constraints:
 - signature should be part of path
 - body size is not limited

The "in path" signature can not be used inside a query parameter and vice-versa.