Connectors and webhooks

A connector teaches CodeKasten to talk to another service: how to sign in to it, which actions it offers, and which webhooks it sends.

Three places

Where	What happens there
A connector workspace (/!core)	The connector is defined and released, like an app
Marketplace	A workspace installs the connector
Integrations	The workspace links the accounts its workflows should use

Accounts and credentials

Linking an account signs in to the other service (with OAuth, where the service uses it) and stores the credentials encrypted. A workspace can link several accounts of one connector, and each person can link their own.

Credentials are never synced to the browser and never shipped in a package.

Using a connector in a workflow

• The Connector Action step calls an action with a linked account. The step's ports are the action's inputs and outputs.
• The Connector Trigger starts a workflow when the connector receives a webhook.

Actions that send a file

A connector action can send the content of a file record: a video to a channel, a document to a drive. In the connector builder, a REST action has an Upload tab; switch on This action sends a file and say how the service wants it.

Setting	What it means
Input that names the file	In a workflow, this input of the step is given the id of a file record of the branch
How the file is sent	As one request's body, in pieces (each with a Content-Range), or as a form (multipart/form-data)
Send the file to	Empty: the file goes with the action's own request. Set: the action's own request is sent first, without the file, and this is where the file goes afterwards
Request after the file	Optional: a request that publishes or commits what was sent
The step's output	Which request's answer the workflow gets

Most services that take large files work in two or three requests, and the settings follow that:

1. Start. The action's own request announces the file. The service answers with where to send it.
2. Transfer. The file is sent there.
3. Finish. Where the service wants it, a last request publishes the upload.

A value goes into a template as typed. To put a text into a JSON body, write {{title|json}}: it is the value as JSON, in quotes and with quotes and line breaks escaped, and null when there is none. This works in every action, not only in those that send a file.

Besides the action's inputs, the path, headers and bodies of such an action can use:

Variable	Is
{{file.name}}, {{file.size}}, {{file.type}}	The file's name, its size in bytes and its type
{{upload.chunkSize}}, {{upload.chunkCount}}	The size of a piece and how many there are
{{start.headers.location}}, {{start.body.…}}	What the first request was answered: a header (lower case), or a path into its JSON
{{transfer.body.…}}	What the file was answered, for the request after it

For example, a resumable upload in the style many video services use:

• the action: POST /upload/videos?uploadType=resumable, with the header X-Upload-Content-Length: {{file.size}} and the video's title in the body;
• Send the file to: {{start.headers.location}}, in pieces of 8 MiB.

What to know:

• The action runs in a workflow only: the builder's Send button has no file to send.
• The file is passed from storage to the service without being kept in between. A step may take up to an hour.
• The account's credential goes with the file only when the file is sent to the connector's own host, unless you say otherwise. An address a service hands out for the upload usually needs none.
• Nothing is sent twice by itself. A piece of a file that fails is sent again up to three times, because a piece says which bytes it is. Anything else that fails once part of the file may have arrived fails the step, and a person decides whether to run it again.

Webhooks

The other service sends webhooks to the dispatcher:

POST https://<your-host>/hooks/<connector id>

A delivery starts every workflow whose trigger accepts it. The delivery id is used as the run's identity, so a webhook that is sent twice starts nothing twice.

Deliveries are rate limited per sender and per connector.

State of this area

Connectors are the youngest part of CodeKasten. Core Connectors ships one connector, YouTube, which has not yet been run against the real service; webhook signatures are not verified against a per-connector secret, and agents cannot build workflows with connector steps.