Actions and delivery handlers

An action is a stable identifier plus metadata and a delivery handler. incld stores the declaration and sends signed events; the handler and its side effects remain in your application.

Define actions

const actions = defineActions({
 sync_contacts: {
  displayName: "Sync contacts",
  description: "Refresh active CRM contacts",
  payloadSchema: {
   type: "object",
   properties: { segment: { type: "string" } },
   required: ["segment"],
  },
  configuration: { timeoutSeconds: 30 },
  async run({ action, payload, event, request, client }) {
   await jobs.enqueue("sync_contacts", payload, {
    deduplicationKey: event.idempotencyKey,
   })
  },
 },
})

Definition field	Type	Meaning
displayName	string?	Human label. Defaults to a humanized identifier.
description	string?	Operator-facing explanation of the action.
payloadSchema	JSON Schema object?	Contract recorded in the registry and available to tooling.
configuration	object?	Application-specific action metadata.
run	IncldActionHandler	Required delivery handler for scheduled runs and bulk chunks.

Handler input

Value	Type	Notes
action	string	The stable identifier that selected this handler.
payload	Payload	Schedule payload, or a Bulk payload containing operation/chunk IDs, index, items, and metadata.
event.idempotencyKey	string	Stable event ID. Deduplicate every external side effect with this value.
event.scheduleId	string?	Present for scheduled runs.
event.runId	string?	Present for scheduled runs.
event.context	{ organization_id, user_id? }	Trusted tenant identity copied from the durable Schedule or Bulk operation.
request	Request	The verified incoming webhook request.
client	Incld	Authenticated follow-up client automatically scoped from event.context.

Synchronize action metadata

// deployment task or application startup hook
await incld.syncActions()

Synchronization defines or updates every declared action by identifier. It is explicit and idempotent. Run it after the new application code is deployable and before users create Schedules or Bulk operations that reference a new identifier.

Delivery behavior

Acknowledgement is not completion

Keep the handler bounded. For expensive work, enqueue a job using the event idempotency key, then return. A timeout can cause redelivery even if your first attempt continued running.

Event	Handler payload
run.created	The schedule payload snapshot; event includes scheduleId, runId, organization_id, and user_id context.
bulk.chunk	{ operationId, chunkId, chunkIndex, items, metadata }; event context includes organization_id.
Unknown action	Rejected by the adapter; no arbitrary code dispatch.
Unknown event type	Acknowledged without dispatch when it is not an action delivery event.