SDK

Integration paths

Path	Use it when
Listener Delivery	You want your code to receive work from Arklow directly.
External Work	An existing pipeline starts and executes the work.

Performance

The expected delivery latency from work entering Arklow to reaching your listener(s) is between 150-300ms. Each lane can drive approximately 24 messages per second, or 1440 messages per minute. To increase throughput, use more lanes. There isn’t a maximum per-second limit. The maximum lanes that can be used by default, are detailed here.

Lanes with zero outstanding work for some time can take up to 4 seconds to calibrate, and deliver work. Once calibrated, delivery latency has no added delay.

Authentication

Listener delivery and external registration authenticate with an Arklow organization API key.

Listener Delivery

Setup

Open the destinations page

Go to Destinations and click Create destination.

Pick the type

Set Destination Type to SDK.

Choose a namespace

Enter the namespace your listeners will use.

Link the destination

Create the destination, then link it from the action’s Flow tab.

Listener options

Option	Behavior
`namespace`	Claims work from every active SDK destination in the organization with the same namespace
`maxOutstanding`	(Optional) Sets the maximum number of unsettled deliveries this listener can hold
`variants`	Limits claims to the named action variants; an omitted or empty list accepts every variant
`transport`	Uses `grpc` by default; use `poll` to claim over HTTPS

When using the optional field maxOutstanding, there are some important things to note.

It’s important to use .defer() if the work will be asynchronous, or not handled by the code that takes delivery of the work. This frees up slots for further delivery.
Setting the value too low can impact Arklow’s delivery choices. We recommend keeping it default unless you run into memory constraints.

It is not recommended to only use a single listener.

Start the listener

Call listen(options, handler) on the listener client.

// Other SDK languages follow the same form.
const running = listener.listen(
  {
    namespace: "billing",
    variants: ["invoice.process"]
  },
  async (delivery) => {
    await processInvoice(delivery.payload);
  },
);

Delivery fields

Field	Value
`actionRecordId`	Stable action identity across attempts
`attempt`	Delivery attempt number
`variant`	Action definition variant
`payload`	Action payload
`tags`	Tags attached to the action, when present
`leaseDeadlineAt`	Current claim deadline
`timeoutAt`	Action timeout, when one applies

Settlement

Method	Effect
`await delivery.ack()`	Marks the action as succeeded
`await delivery.nack()`	Rejects the attempt and allows redelivery
`await delivery.nack({ retryAt })`	Schedules the next attempt for the supplied `Date`
`await delivery.nack({ retry: false })`	Marks the failure as permanent
`await delivery.extend(ms)`	Extends the current lease within the action timeout

The first explicit acknowledgement or rejection takes precedence over the handler result.

Leases

A claim begins with a 60-second lease, shortened when the action timeout is nearer. The client renews the lease while the handler remains open. An expired claim can be delivered again, unless .defer() is called. Use actionRecordId as the idempotency key across attempts. Delivery guarantees talks about delivery behavior that can be important.

Shutdown

Call await running.stop() during shutdown. The listener stops claiming work and waits for its current handlers and settlements to finish. A handler that never settles also prevents stop() from completing.

External Work

Call registerExternalWork after an existing pipeline starts work that Arklow should track. Registration creates an action record and bypasses admission because execution has already begun. After rules select its destination and lane, the work contributes to that lane’s external running count until completion or expiry.

// Other SDK languages follow the same form.
const work = listener.registerExternalWork("invoice.process", {
  externalRef: invoiceJob.id,
  tags: { customer_id: invoiceJob.customerId },
  payload: invoiceJob.payload,
  timeout: 900,
});

const actionRecordId = await work.recordId;

Option	Behavior
`variant`	Selects the action definition for the record
`externalRef`	Uses an existing job identifier as an idempotency key
`tags`	Attaches work identity and routing context
`destinationId`	(Optional) Associates the record with a destination linked to the definition
`payload`	Stores the action payload
`timeout`	Sets the maximum lifetime in seconds; defaults to `3600` and accepts `1` through `86400`

When destinationId is omitted, the action’s normal rule and default-destination selection apply. Reusing an externalRef returns the existing action record. Supply a stable reference when registration may be retried; otherwise the client generates one.

External work handle

Member	Behavior
`recordId`	Resolves to the Arklow action ID
`update()`	Extends the activity lease while the external work remains active
`complete()`	Marks the action as succeeded
`toJSON()`	Serializes the identifiers needed to resume tracking in another process

Registration starts a 60-second activity lease. Call update() on a cadence shorter than 60 seconds while the work remains active. The client coalesces calls made before another extension is needed, and the lease cannot move beyond the action timeout. This is currently 24 hours. Await recordId before calling toJSON(). Restore the serialized handle after a process handoff or restart with externalWorkHandle().

External work has no rejection or retry settlement. When a lease expires, it also marks the action as complete.

Getting started

Fundamentals

Integration paths

Performance

Authentication

Listener Delivery

Setup

Listener options

Start the listener

Delivery fields

Settlement

Leases

Shutdown

External Work

External work handle

​Integration paths

​Performance

​Authentication

​Listener Delivery

​Setup

​Listener options

​Start the listener

​Delivery fields

​Settlement

​Leases

​Shutdown

​External Work

​External work handle

Integration paths

Performance

Authentication

Listener Delivery

Setup

Listener options

Start the listener

Delivery fields

Settlement

Leases

Shutdown

External Work

External work handle