Events

Emit events from your app to start every workflow that listens for them, and to wake the runs waiting on their key.

An event records that something happened in your app, like user.created or invoice.paid. You emit it once, and Nelkap does two things with it:

• It starts a run of every workflow that listens for the event.
• It wakes every run waiting on the event’s key, if the event has one.

The code that emits the event doesn’t need to know what happens next. To react to a sign-up in a new way, you add a workflow that listens for user.created, without touching the sign-up code.

Listen for an event

List the events a workflow listens for when you register it:

nelkap/index.ts

nelkap.registerWorkflows([
  {
    name: 'onboardUser',
    handler: onboardUser,
    events: ['user.created'],
  },
  {
    name: 'addToNewsletter',
    handler: addToNewsletter,
    events: ['user.created'],
  },
]);

A workflow can listen for up to 100 events. Each run it starts receives the event’s payload as its own payload, so the workflow’s argument has the payload’s type:

export async function addToNewsletter(userId: string) {
  await nelkap.step.run('subscribe', () =>
    subscribeToNewsletter(userId),
  );
}

Emit an event

Call nelkap.emit from your server code:

const { runIds } = await nelkap.emit({
  event: 'user.created',
  payload: 'user_42',
});

Here, one event starts two runs, one of onboardUser and one of addToNewsletter, both with the payload user_42. emit returns the IDs of the runs it started, or an empty list if no workflow listens for the event.

Field	Required	What it sets
event	Yes	The event’s name, up to 256 characters.
payload	No	Any JSON value, passed to every run the event starts, and returned by every wait it wakes.
tags	No	Up to 10 labels, each up to 128 characters, given to every run the event starts.
wakeOn	No	The key of the waiting runs to wake, up to 256 characters.

Name events after what happened, in the past tense, like order.shipped. A name that says what happened, rather than which workflow should run, lets the list of listeners grow without changing the code that emits it.

Wake waiting runs

A run can pause until an event arrives with a given key, with step.wait. To wake it, emit an event with wakeOn set to that key:

await nelkap.emit({
  event: 'refund.reviewed',
  payload: { approved: true },
  wakeOn: 'refund_ord_42',
});

Every run waiting on refund_ord_42 resumes, and its step.wait returns the event’s payload. The same event also starts the workflows that listen for refund.reviewed, like any event. The IDs emit returns are those of the runs it started, not of the runs it woke.

An event wakes only the runs already waiting when it arrives. An event emitted before the run reaches its wait doesn’t wake it later. See Events sent before the wait.

Emit from a workflow

A workflow can emit events too, for example to let other workflows know that an order shipped. Emit inside a step, so the event goes out once, even when the run resumes later:

await nelkap.step.run('shipped event', () =>
  nelkap.emit({
    event: 'order.shipped',
    payload: orderId,
  }),
);

Events from other services

Services like a payment provider can’t call nelkap.emit, but they can call a URL. A webhook gives you that URL, and turns each call into an event. See Webhooks.

Event history

The Events page of the console lists every event, whether your app emitted it or a webhook received it, with its project, the time it arrived, and the number of runs it started. Filter events by name, by project, by period, or by whether they started any run, for example to find events no workflow listened for.

Events are kept for the history of your plan, like runs. See Retention.

Errors

Error	When
NelkapError badRequest	A field breaks a limit above. issues says which.
NelkapError payloadLimitReached	The payload is larger than your plan allows.
NelkapError throughputLimitReached	Your workspace made more requests this second than your plan allows.

Every code is described in Errors.