Workflows and events
Workflows run multi-step sequences that can wait for days. Define them in code with workflow(), or as JSON through this API.
Create a JSON workflow
POST/v1/workflows
Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.
Stores a workflow definition, replacing any with the same name. A workflow registered in code with workflow() under the same name takes precedence.
Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The name you trigger it by. |
steps | object[] | yes | Run in order. See the step types below. |
Step types
| Step | Fields |
|---|---|
notify | payload: any notify body. With no user, segment or topic it sends to the instance's user. |
wait | duration: a number with ms, s, m, h or d, like "3d" or "1.5h". |
waitForEvent | event: the event name. options.timeout: a duration, default "24h". options.match: fields the event's properties must equal (dot paths allowed). |
JSON workflows can't branch. Use a code workflow for conditions. An invalid duration is accepted here and fails the instance when the step runs.
Responses
{
"name": "onboarding"
}
{
"error": "validation_error",
"issues": [
{
"path": "steps.0.action",
"message": "Invalid discriminator value. Expected 'notify' | 'wait' | 'waitForEvent'"
}
]
}
Common errors (401, 400, 403, 429, 413, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "forbidden",
"message": "API key is read-only"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "malformed_json",
"message": "malformed_json"
}
{
"error": "payload_too_large",
"message": "payload_too_large"
}
{
"error": "internal_error"
}
Example
curl -X POST http://localhost:3000/v1/workflows \
-H "Authorization: Bearer $NK_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "onboarding",
"steps": [
{ "action": "notify", "payload": { "template": "welcome" } },
{ "action": "wait", "duration": "1d" },
{ "action": "notify", "payload": { "template": "tips" } }
]
}'
await notifkit.createWorkflow({
name: "onboarding",
steps: [
{ action: "notify", payload: { template: "welcome" } },
{ action: "wait", duration: "1d" },
{ action: "notify", payload: { template: "tips" } },
],
});
List JSON workflows
GET/v1/workflows
Auth: Project key, or the admin key or a session with x-project-id.
Definitions stored through this API. Workflows registered in code don't appear.
Query parameters
| Name | Type | Default | Description |
|---|---|---|---|
search | string | Substring of the name. | |
limit | number | all | 1 to 100. |
Responses
{
"workflows": [
{
"id": "c3e1a2b4-5d6f-4a7b-8c9d-0e1f2a3b4c5d",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"name": "onboarding",
"steps": [
{
"action": "notify",
"payload": {
"template": "welcome"
}
},
{
"action": "wait",
"duration": "1d"
},
{
"action": "notify",
"payload": {
"template": "tips"
}
}
],
"createdAt": "2026-11-10T12:00:00.000Z"
}
]
}
{
"workflows": []
}
Common errors (401, 400, 429, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "internal_error"
}
Example
curl http://localhost:3000/v1/workflows -H "Authorization: Bearer $NK_KEY"
const { workflows } = await notifkit.listWorkflows({ search: "onboarding" });
Trigger a workflow
POST/v1/workflows/trigger
Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.
Starts one instance. Steps without a target send to input.user.id, so trigger one instance per user. An unknown name still answers 202, and the instance never starts, so GET on it returns 404.
Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Code or JSON workflow name. |
input | object | no | Passed to the handler as event. |
user | string or object | no | Shorthand for input.user. An object is an inline user, saved first. If saving fails, the instance still starts. |
Responses
{
"messageId": "1731837600000-0",
"instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83"
}
{
"error": "validation_error",
"issues": [
{
"path": "name",
"message": "Invalid input: expected string, received undefined"
}
]
}
Common errors (401, 400, 403, 429, 413, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "forbidden",
"message": "API key is read-only"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "malformed_json",
"message": "malformed_json"
}
{
"error": "payload_too_large",
"message": "payload_too_large"
}
{
"error": "internal_error"
}
Example
curl -X POST http://localhost:3000/v1/workflows/trigger \
-H "Authorization: Bearer $NK_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "onboarding", "user": "usr_123" }'
const { instanceId } = await notifkit.triggerWorkflow({ name: "onboarding", user: "usr_123" });
Get an instance
GET/v1/workflows/instances/{id}
Auth: Project key, or the admin key or a session with x-project-id.
status is pending (waiting to start, or suspended on a wait), running, completed, failed or canceled. steps holds each finished step in call order. A notify step stores what notify returned, a wait step stores its wake-up time in milliseconds, a run step stores its result, and a waitForEvent step stores null while waiting, then the event's properties, or { "timedOut": true }. waiters lists any open waitForEvent.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | instanceId from the trigger. |
Responses
{
"id": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"name": "invite",
"status": "pending",
"input": {
"user": {
"id": "usr_123"
}
},
"createdAt": "2026-11-17T10:00:00.000Z",
"updatedAt": "2026-11-20T10:00:05.000Z",
"steps": [
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
"stepIndex": "0",
"action": "notify",
"output": {
"success": true,
"messageId": "1731837600000-4",
"notificationId": "d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f6a"
},
"error": null,
"createdAt": "2026-11-17T10:00:00.420Z"
},
{
"id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
"stepIndex": "1",
"action": "wait",
"output": {
"scheduledAt": 1732096800420
},
"error": null,
"createdAt": "2026-11-17T10:00:00.431Z"
},
{
"id": "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
"stepIndex": "2",
"action": "waitForEvent",
"output": null,
"error": null,
"createdAt": "2026-11-20T10:00:05.000Z"
}
],
"waiters": [
{
"id": "d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70",
"projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"instanceId": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83",
"eventName": "invite.accepted",
"matchCriteria": {
"userId": "usr_123"
},
"expiresAt": "2026-11-21T10:00:05.000Z",
"createdAt": "2026-11-20T10:00:05.000Z"
}
]
}
{
"error": "workflow_not_found",
"id": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83"
}
Common errors (401, 400, 429, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "internal_error"
}
Example
curl http://localhost:3000/v1/workflows/instances/9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83 -H "Authorization: Bearer $NK_KEY"
const instance = await notifkit.getWorkflow(instanceId);
Cancel an instance
DELETE/v1/workflows/instances/{id}
Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.
Cancels a pending or running instance and removes its waiters. Remaining steps never run.
Path parameters
| Name | Type | Description |
|---|---|---|
id | string | Instance id. |
Responses
No body.
{
"error": "workflow_not_cancelable",
"id": "9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83"
}
Common errors (401, 400, 403, 429, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "forbidden",
"message": "API key is read-only"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "internal_error"
}
Example
curl -X DELETE http://localhost:3000/v1/workflows/instances/9f2c7a1e-5b3d-4c8e-a6f0-2d1e4b7c9a83 -H "Authorization: Bearer $NK_KEY"
await notifkit.cancelWorkflow(instanceId);
Send an event
POST/v1/events
Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.
Wakes every instance waiting on this event name whose match fields equal the event's properties. The waiting step resolves to properties. An event nobody waits for is accepted and does nothing.
Headers
| Header | Type | Description |
|---|---|---|
x-timestamp | date | With x-expiry: when the event happened. |
x-expiry | seconds | Rejects the event once x-timestamp plus this has passed. |
Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Event name, like invite.accepted. |
properties | object | yes | Event data. Match criteria are checked against it. |
Responses
{
"messageId": "1731837600000-5",
"eventId": "5d7a8b9c-0d1e-4f2a-8b3c-4d5e6f7a8b9c"
}
{
"error": "validation_error",
"issues": [
{
"path": "properties",
"message": "Invalid input: expected record, received undefined"
}
]
}
{
"error": "event_expired",
"message": "Webhook event is expired"
}
{
"error": "invalid_timestamp",
"message": "x-timestamp and x-expiry must be a date and a number of seconds"
}
Common errors (401, 400, 403, 429, 413, 500)
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
{
"error": "bad_request",
"message": "x-project-id header or projectId query param required when using admin token"
}
{
"error": "forbidden",
"message": "API key is read-only"
}
{
"error": "too_many_requests",
"message": "Project rate limit exceeded (max 600 req/min)"
}
{
"error": "malformed_json",
"message": "malformed_json"
}
{
"error": "payload_too_large",
"message": "payload_too_large"
}
{
"error": "internal_error"
}
Example
curl -X POST http://localhost:3000/v1/events \
-H "Authorization: Bearer $NK_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "invite.accepted", "properties": { "userId": "usr_123" } }'
await notifkit.ingestEvent({ name: "invite.accepted", properties: { userId: "usr_123" } });