Monitor Workflow Status

Guides: Monitor Workflow Status

Once you've created a Workflow, you'll often need to check its progress or retrieve its final status. This guide covers how to monitor a workflow using the SignStack API.

Fetching Workflow Status and Details

The primary way to monitor a workflow is by fetching its current state using its unique id.

Endpoint: GET /v1/organizations/{organizationId}/workflows/{workflowId}
Authentication: Requires a valid, short-lived SignStack JWT Access Token.
Response: Returns the full Workflow object, including its current overall status, the status of each individual step, and participant task statuses.

Example curl Request:

curl -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  "[https://api.signstack.com/v1/organizations/me/workflows/wf_123abc456def]"

Example Response (truncated):

{
  "id": "wf_123abc456def",
  "organizationId": "org_...",
  "status": "InProgress", // Overall status
  "displayName": "Standard Employee Onboarding - John Doe",
  "participants": [
    // ... participant details ...
  ],
  "documents": [
    // ... document details ...
  ],
  "steps": [
    {
      "stepId": "step_newHireSign",
      "stepKey": "newHireSigning",
      "type": "PARTICIPANT_TASK",
      "status": "InProgress", // Status of this specific step
      "participantTask": {
        "participantId": "p_john_doe_...",
        "status": "Sent", // Status of the participant's task
        // ... other task details ...
      }
    },
    {
      "stepId": "step_hrCountersign",
      "stepKey": "hrCountersign",
      "type": "PARTICIPANT_TASK",
      "status": "Pending", // This step hasn't started yet
      // ...
    }
  ],
  "eventLog": [
    // ... chronological history of events ...
  ],
  "createdAt": "...",
  "updatedAt": "..."
}

Understanding Workflow Statuses

The top-level status field on the Workflow object tells you the overall state:

Draft: The workflow has been created but not yet sent.
InProgress: The workflow has been sent and is actively moving through its steps.
Completed: All required steps have finished successfully. The final documents are ready.
Failed: An error occurred during execution (e.g., a validation failed, an API call failed). Check the eventLog for details.
Voided: The sender intentionally cancelled the workflow before completion.

You can check the status field on individual steps and participantTask objects for more granular progress information.

Using Webhooks for Real-Time Updates (Recommended)

While polling the GET /workflows/{workflowId} endpoint works, it's inefficient for real-time tracking. The recommended way to monitor workflows is by using Webhooks. 🎣

Concept: You provide SignStack with a secure URL (your webhook endpoint). SignStack will automatically send a POST request to your URL whenever a significant event happens in a workflow (e.g., STEP_COMPLETED, WORKFLOW_COMPLETED, WORKFLOW_FAILED).
Benefit: Your application receives real-time updates without needing to constantly poll the API, enabling faster and more efficient integrations.
Setup: Configure your webhook endpoint in your SignStack organization settings. (See the Webhooks Guide for detailed setup instructions).

By using either direct API polling or, preferably, webhooks, you can effectively monitor the progress of your workflows and trigger downstream actions in your own application when they complete or change state.

➡️ Next: Guides: Handle Participant Actions