workflow-notify

Simple webhook notifications for Workflow DevKit workflows.

Get notified when your workflows succeed or fail - no polling, no external infrastructure.

Installation

npm install workflow-notify

Quick Start

1. Create your notification wrapper (once)

// lib/notify.ts
import { createNotify } from "workflow-notify"

export const withNotify = createNotify({
    onFailure: {
        url: process.env.SLACK_WEBHOOK_URL!
    }
})

2. Wrap your workflow starts

import { withNotify } from "@/lib/notify"
import { start } from "workflow/api"
import { myWorkflow } from "@/lib/workflows"

// Just wrap start() with withNotify()
const run = await withNotify(start(myWorkflow, [arg1, arg2]))

That's it. When the workflow fails, your webhook is called.

How It Works

withNotify(start(...))
        │
        ▼
┌───────────────────┐
│ Workflow starts   │ ─── Returns immediately with run ID
│ (non-blocking)    │
└───────────────────┘
        │
        ▼ (background)
┌───────────────────┐
│ Await completion  │ ─── Uses SDK's Run.returnValue
└───────────────────┘
        │
        ▼
┌───────────────────┐
│ Send webhook      │ ─── POST to your configured URL
└───────────────────┘

• Non-blocking: withNotify() returns immediately after the workflow starts
• No polling infrastructure: Uses the SDK's built-in Run.returnValue promise
• Fire and forget: Notification failures are logged but don't affect your app

Configuration

Basic (failure only)

export const withNotify = createNotify({
    onFailure: {
        url: process.env.SLACK_WEBHOOK_URL!
    }
})

With success notifications

export const withNotify = createNotify({
    onFailure: {
        url: process.env.ALERT_WEBHOOK_URL!
    },
    onSuccess: {
        url: process.env.ANALYTICS_WEBHOOK_URL!
    }
})

With custom headers

export const withNotify = createNotify({
    onFailure: {
        url: "https://api.pagerduty.com/incidents",
        method: "POST",
        headers: {
            "Authorization": `Bearer ${process.env.PAGERDUTY_TOKEN}`,
            "X-Routing-Key": process.env.PAGERDUTY_ROUTING_KEY!
        }
    }
})

Webhook Payload

Your webhook receives a JSON POST with this structure:

{
    "workflowName": "workflow//src/lib/payments.ts//processPayment",
    "status": "failed",
    "error": "PaymentDeclinedError: Insufficient funds",
    "result": null,
    "runId": "wrun_01ABC123DEF456",
    "timestamp": "2026-01-27T15:30:00.000Z"
}

| Field | Type | Description | |-------|------|-------------| | workflowName | string | Full workflow identifier | | status | "success" | "failed" | Completion status | | error | string | null | Error message (when failed) | | result | any | Return value (when succeeded) | | runId | string | Workflow run ID for debugging | | timestamp | string | ISO 8601 completion time |

Multiple Notification Profiles

Create different wrappers for different use cases:

// lib/notify.ts
import { createNotify } from "workflow-notify"

// Critical: Page on-call
export const withCriticalNotify = createNotify({
    onFailure: { url: process.env.PAGERDUTY_WEBHOOK! }
})

// Standard: Slack alert
export const withNotify = createNotify({
    onFailure: { url: process.env.SLACK_WEBHOOK! }
})

// Analytics: Track all completions
export const withAnalytics = createNotify({
    onSuccess: { url: process.env.ANALYTICS_URL! },
    onFailure: { url: process.env.ANALYTICS_URL! }
})

// Use the appropriate wrapper
await withCriticalNotify(start(paymentWorkflow, [...]))
await withNotify(start(emailWorkflow, [...]))
await withAnalytics(start(reportWorkflow, [...]))

API Reference

createNotify(options)

Creates a notification wrapper function.

function createNotify(options: NotifyOptions): <T>(startPromise: Promise<T>) => Promise<T>

Options:

| Option | Type | Required | Description | |--------|------|----------|-------------| | onFailure | WebhookConfig | No | Webhook for failed workflows | | onSuccess | WebhookConfig | No | Webhook for successful workflows |

WebhookConfig:

| Field | Type | Required | Description | |-------|------|----------|-------------| | url | string | Yes | Webhook URL | | method | "POST" | "PUT" | "PATCH" | No | HTTP method (default: POST) | | headers | Record<string, string> | No | Additional headers |

Requirements

• Node.js 18+
• workflow package >= 4.0.0

License

MIT