Workflow Notifications via SSE

Table of Contents

• Introduction
• Prerequisites
• How It Works
• Steps to Use SSE
• Example Event Payload
• Statuses
• Summary
• Sample SSE Clients

Introduction

Wexflow allows clients to subscribe to real-time notifications via Server-Sent Events (SSE) for workflow job status updates. This enables your application to receive a push notification when a workflow job finishes or stops, without polling the API repeatedly.

You can subscribe to a Server-Sent Events (SSE) endpoint that notifies your client when a workflow job finishes or stops.

Prerequisites

SSE is available in the .NET 9.0+ versions of Wexflow:

• wexflow-x.x-windows-netcore.zip
• wexflow-x.x-linux-netcore.zip
• wexflow-x.x-macos-netcore.zip

Ensure you are using one of these distributions. SSE is not available in the .NET Framework 4.8 version.

How It Works

1. You start a workflow using the REST API.
2. You receive a jobId in the response.
3. You subscribe to the SSE endpoint using that workflowId and jobId.
4. Wexflow will push a notification to your client when the job finishes or stops.
5. The SSE connection is automatically closed after sending the final event.

Steps to Use SSE

1. Start a Workflow

Use the REST API to start a workflow and receive the jobId:

POST /api/v1/start?w={workflowId}
Authorization: Bearer <JWT_TOKEN>

For example:

POST http://localhost:8000/api/v1/start?w=41

2. Connect to the SSE Endpoint

Connect to the following endpoint using the returned jobId:

GET /api/v1/sse/{workflowId}/{jobId}
Authorization: Bearer <JWT_TOKEN>
Accept: text/event-stream

For example:

GET http://localhost:8000/api/v1/sse/41/66aae8f4-e3ab-4fdc-8db2-a0a7692d8906

The server will keep the connection open until the workflow job ends.

Example Event Payload

Once the workflow finishes or stops, you will receive an event like:

{
  "workflowId": 41,
  "jobId": "66aae8f4-e3ab-4fdc-8db2-a0a7692d8906",
  "status": "Done",
  "name": "Workflow_Wait",
  "description": "Workflow_Wait"
}

To test SSE, try running a workflow like Workflow_Wait with a 10-second delay.

Statuses

Here are the possible statuses sent by the SSE event:

Status	Description
Pending	Job is queued and waiting to start
Running	Job is currently in progress
Done	Job completed successfully
Failed	Job ended with an error
Warning	Job completed with warnings
Disabled	Job or workflow is disabled
Stopped	Job was manually stopped
Rejected	Job was rejected or not accepted

Summary

• The SSE event returns JSON with:
  { workflowId, jobId, status, name, description }
• Connection closes automatically when the workflow job ends.
• Always include a valid JWT Bearer token in the request headers.
• Useful for real-time job monitoring or triggering actions upon workflow completion.

Sample SSE Clients

Here are SSE client examples in different languages:

• C# SSE Client
• JavaScript SSE Client
• PHP SSE Client
• Python SSE Client
• Go SSE Client
• Rust SSE Client
• Ruby SSE Client
• Java SSE Client
• C++ SSE Client

You can find the source code for all these SSE clients in the samples/clients/sse directory of the main Wexflow repository.

These examples serve as practical starting points to integrate Wexflow Push Notifications (SSE) into your own applications regardless of the tech stack you're using.