Apps in Workflows

Orbit workflows run on form submissions, booked meetings, deal stage changes and imports, and send data to CRMs, Slack, webhooks and more. Your app can be one of those steps. Turn on Available in workflows for the app in the Developer Portal, declare the actions it offers, and every workspace that has installed your app sees them in the workflow editor’s Installed apps section as “App: Action”.

Do you need this?

Two kinds of apps exist, and the difference is only where the app shows up:

	API and webhooks	API, webhooks and workflows
Connects over OAuth, reads and writes the workspace’s data	Yes	Yes
Receives webhook events	Yes	Yes
Appears in the workflow editor as a step people can add	No	Yes, as “App: Action” under Installed apps
What you build	Your own sync, on your schedule	An HTTPS endpoint per action that receives signed deliveries when a workflow runs
Where to choose	The Where your app appears choice when you register the app, or the Workflows card on the app page later

Pick API and webhooks when your app pulls or pushes data on its own (a CRM sync, an analytics import, an enrichment tool that reads contacts). Pick workflows when a workspace should be able to decide, per workflow, to send something to your app at a particular step (“when this form is submitted, send the event to App”). The portal shows a preview of the step before you turn it on, and you can change your mind later: turning it on for an approved app is a change request (you get the signing secret and can define actions right away; workspaces see the app once the request is approved), turning it off applies immediately. Running the step POSTs the inputs the workspace mapped to your endpoint, signed with your app’s action signing secret. Nothing is sent to workspaces that have not installed the app, and deliveries stop on their own when a workspace uninstalls it.

Declare an action

An action has:

Field	Meaning
`key`	Stable snake_case identifier your endpoint switches on, unique per app (`send_event`)
`name`	What the workspace sees (`Send event`)
`description`	Optional, shown under the step in the editor
`endpoint_url`	HTTPS URL on a public host that receives deliveries
`inputs`	The values a workspace maps when it adds the step: each has a `key`, a `label`, a `type` (`string`, `number`, `boolean`), whether it is `required`, and an optional `description`

Declare up to 20 actions per app and 30 inputs per action. The workspace maps each input from its workflow fields ({{email}}, {{deal.amount}}, a literal) in the step’s panel; required inputs must be mapped before the workflow can be activated, and a run whose required input renders empty for that contact fails the step without calling you. Manage actions on the app’s page in the portal, or over the API with the app owner’s session:

Method	Endpoint	Description
`PATCH`	`/api/developer/apps/:id`	`{ "workflow_actions_enabled": true }` turns the feature on; the first time, the response carries `action_signing_secret` once
`GET` / `POST`	`/api/developer/apps/:id/actions`	List / create (`key`, `name`, `description`, `endpoint_url`, `inputs`, `is_active`)
`PATCH` / `DELETE`	`/api/developer/apps/:id/actions/:actionId`	Change any field or turn the action off (`is_active: false`) / delete it
`POST`	`/api/developer/apps/:id/actions/secret`	Rotate the signing secret (returned once)

Turning an action off keeps the steps workspaces built; they fail with “the app turned off Action” until it is on again. Deleting it does the same, for good.

The delivery

Each run of the step is one POST to your endpoint:

{
  "id": "0b3f6c8e-...",
  "event": "workflow.action",
  "app": { "client_id": "orb_client_..." },
  "action": { "key": "send_event", "name": "Send event" },
  "team_id": "7c1d0e2f-...",
  "workflow": { "id": "e4a1...", "name": "Demo requests", "run_id": "9f2b...", "node_id": "3c7d..." },
  "trigger": { "submission_id": "5a1e...", "form_id": "88c0..." },
  "contact": { "id": "5c6d7e8f-...", "email": "[email protected]" },
  "inputs": { "event_name": "purchase", "amount": 1200, "is_trial": false },
  "occurred_at": "2026-10-27T20:00:00.000Z"
}

team_id is the workspace that installed your app (the same id GET /api/v1/me and the webhook envelope carry), so you can look up the right account. inputs holds every declared input, typed as declared; an optional input the workspace left unmapped is null. Use contact.id with GET /api/v1/contacts/:id for anything beyond what was mapped. Headers:

Header	Value
`X-Orbit-Signature`	`sha256=<HMAC-SHA256 of the raw body with your action signing secret>`
`X-Orbit-Event`	`workflow.action`
`X-Orbit-Action`	The action `key`
`X-Orbit-App`	Your app’s `client_id`
`X-Orbit-Delivery-ID`	The body’s `id`, unique per attempt
`X-Orbit-Timestamp`	The body’s `occurred_at`
`X-Orbit-Attempt`	Present on retries

Verify the signature exactly as for webhooks, with the action signing secret instead of the webhook secret. The secret is shown once when you turn the feature on and can be rotated from the portal; rotate it before you change your verification, as deliveries use the new secret from the next run.

Your response

A 2xx means the step succeeded. A JSON body with an outputs object ({ "outputs": { "cometly_event_id": "evt_9" } }) is kept with the run and available to later steps; values are strings, numbers or booleans, at most 50 keys.
408, 425, 429, any 5xx, a timeout (20 seconds) or a connection error is retried up to three times with backoff, like any destination step.
Any other 4xx is treated as your app refusing the call: the step fails at once with your response text in the run’s error, and is not retried.

For workspaces and agents

In the editor, installed apps’ actions appear under Installed apps in the add-step menu once the app is installed; each step’s panel shows your inputs with the workspace’s field picker. Over the API and MCP, GET /api/v1/workflows/schema lists them under app_actions, and a workflow node with "type": "destination", "provider": "app_action" and config { app_id, action_id, action_key, inputs: { "<input key>": "<template>" } } uses one.

Webhooks

Tell your app what happened in a workspace

Workflows API

Build and run workflows from code

Getting Started

Building Apps

Publishing

App Resources

Do you need this?

Declare an action

The delivery

Your response

For workspaces and agents

Webhooks

Workflows API

​Do you need this?

​Declare an action

​The delivery

​Your response

​For workspaces and agents

Webhooks

Workflows API

Do you need this?

Declare an action

The delivery

Your response

For workspaces and agents