Sink Routes

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.

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.

Refer to the CLI command for details.

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).

The diagram outlines the complete event life cycle from it’s invocation to script execution.

@startuml
skinparam ParticipantPadding 20
skinparam BoxPadding 200
skinparam SequenceArrowThickness 2
skinparam RoundCorner 10

actor "External service" as Ext
participant "HTTP request handler" as HttpReqProc
participant "Sink processor" as SinkProc
participant "Eventbus"
participant "EventHandler"
participant "Corredor"

activate Ext
Ext -> HttpReqProc: HTTP request

group Internal
    activate HttpReqProc
    activate SinkProc
    HttpReqProc -> SinkProc: Resolved Sink request

    activate Eventbus
    SinkProc -> Eventbus: Event raised

    activate EventHandler
    Eventbus -> EventHandler: Trigger

    group Automation script
        EventHandler <-> Corredor: Script execution
    end

    Eventbus <- EventHandler: Response
    deactivate EventHandler

    SinkProc <- Eventbus: Response
    deactivate Eventbus

    HttpReqProc <- SinkProc: Response
    deactivate SinkProc
end


HttpReqProc -> Ext: Response
deactivate HttpReqProc
deactivate Ext

@enduml

HTTP request handler

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

The flow outline:

check if the signature is provided,
check if the signature is valid,
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.