You are reading the documentation for an outdated Corteza release. 2023.9 is the latest stable Corteza release.

Sink routes — inbound webhooks

A special resource type that Corteza supports is system sink (system:sink) that is used to respond to API requests. You can use the sink route to implement webhooks; for example, the OAuth flow.

This document focuses mainly on the HTTP request handling. Script invocation and execution are covered in the extensions section.

Security model

Authentication with signature

Each sink URL must be signed for security purposes. The signature is generated based on the parameters (path and constraints) and salted with the JWT secret.

Refer to the CLI command for details.

Corteza will provide alternative ways of securing sink URLs.

Automation script security context

When an HTTP request triggers a script, we are unable to determine who is the invoking user. Because of this, you need to specify the invoking user for the security context (the runAs parameter).

See how security context works in automation scripts.
The diagram outlines the complete event life cycle from it’s invocation to script execution.
Figure 1. The diagram outlines the complete event life cycle from it’s invocation to script execution.

HTTP request handler

The HTTP request handler validates the request and converts it into a sink request.

The flow outline:

  1. check if the signature is provided,

  2. check if the signature is valid,

  3. check if enforced constraints match the request parameters:

    • HTTP method,

    • content-type,

    • expiration time,

    • maximum body size, and so on.

If the above validation passes, the request becomes a sink request and is processed as any other event.

Sink processor

The sink processor takes the HTTP request and converts it into an event that can trigger automation script on the Corredor server.

The most important thing to note here, is that there are slight deviations based on the content-type of the request. When the request indicates an email (message/rfc822, rfc822, email or mail as the Content-Type), the OnReceive system mail (system:mail) event is raised. Any other case, the OnRequest system sink (system:sink) event is raised.

The sink processor also constructs the proper response (headers and body) based on the request.