Evaluate Workflows

Manually trigger workflow evaluation for testing before going live.

Use the evaluate endpoint to test your workflows by simulating an event. This runs the full trigger-matching and action-execution pipeline without requiring a real event to fire.

Endpoint

POST /api/v1/workflows/evaluate

Scope: events:manage

Request body

Field	Type	Required	Description
`eventType`	`string`	Yes	The event type to simulate (e.g. `email.failed`)
`payload`	`object`	Yes	The event payload to pass to matching workflows

Response

{
  "success": true,
  "data": {
    "evaluated": 5,
    "triggered": 2,
    "workflows": [
      {
        "id": "wf_abc123def456",
        "name": "Notify on email failure",
        "triggered": true,
        "actions": [
          {
            "type": "fire_webhook",
            "status": "executed",
            "duration": 245
          }
        ]
      },
      {
        "id": "wf_def456ghi789",
        "name": "Log failed deliveries",
        "triggered": true,
        "actions": [
          {
            "type": "call_api",
            "status": "executed",
            "duration": 180
          }
        ]
      }
    ]
  }
}

Field	Type	Description
`evaluated`	`number`	Total active workflows evaluated
`triggered`	`number`	Number of workflows whose triggers matched
`workflows`	`Array<object>`	Details of each triggered workflow and its action results
`workflows[].actions[].status`	`string`	`executed`, `failed`, or `skipped`
`workflows[].actions[].duration`	`number`	Execution time in milliseconds

Examples

curl

curl -X POST https://api.platformxe.com/api/v1/workflows/evaluate \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "eventType": "email.failed",
    "payload": {
      "messageId": "msg_test_123",
      "to": "jane@example.com",
      "error": "Provider timeout after 30s",
      "attempts": 3
    }
  }'

SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const result = await px.workflows.evaluate({
  eventType: 'email.failed',
  payload: {
    messageId: 'msg_test_123',
    to: 'jane@example.com',
    error: 'Provider timeout after 30s',
    attempts: 3,
  },
});

console.log(`${result.data.triggered} of ${result.data.evaluated} workflows triggered`);
// "2 of 5 workflows triggered"

for (const wf of result.data.workflows) {
  console.log(`${wf.name}: ${wf.actions.map(a => a.status).join(', ')}`);
}
// "Notify on email failure: executed"
// "Log failed deliveries: executed"

Evaluation runs real actions (webhooks are fired, APIs are called). Use a test endpoint URL in your workflow actions during development to avoid side effects.

Run evaluation after creating or updating a workflow to verify trigger matching and action execution before relying on it in production.

Error responses

Code	Description
`BAD_REQUEST`	Missing `eventType` or `payload`
`FORBIDDEN`	API key does not have the `events:manage` scope
`RATE_LIMITED`	Rate limit exceeded for this API key