> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nelkap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Emit events from your app to start the workflows that listen for them, and to wake the runs waiting for them.

An event says that something happened, like `user.created` or `invoice.paid`. Your app emits it, 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.

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:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
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 gets the event's payload as its own payload.

## Emit an event

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
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 their IDs, or an empty list if no workflow listens for the event.

An event takes:

* `event`, its name, up to 256 characters.
* `payload`, if you want, any JSON value, passed to every run it starts.
* `tags`, if you want, up to 10 labels, given to every run it starts.
* `wakeOn`, if you want, the key of the runs it wakes.

Name events after what happened, in the past tense, like `order.shipped`. A name says what happened, never which workflow should run, so the list of listeners can grow freely.

## Wake waiting runs

A run can pause until an event arrives with a given key, using [`step.wait`](https://docs.nelkap.com/guides/wait). To wake it, emit an event with `wakeOn` set to that key:

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
await nelkap.emit({
  event: 'refund.reviewed',
  payload: { approved: true },
  wakeOn: 'refund_ord_42',
});
```

Every run waiting on `refund_ord_42` goes on, and its `step.wait` returns the event's payload. The same event also starts the workflows listening for `refund.reviewed`, like any event.

An event only wakes the runs already waiting when it arrives. See [Wait for an event](https://docs.nelkap.com/guides/wait.md) for how to make sure the run is waiting first.

## Emit from a workflow

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

```ts theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
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 `emit`, but they can call a URL. A webhook gives you that URL, and turns each call into an event. See [Webhooks](https://docs.nelkap.com/triggers/webhooks.md).

## Event history

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.