Webhooks

You can register webhooks to receive execution events. Webhooks can be scoped to a single workflow or registered globally for all workflows in your workspace. Per-workflow webhooks fire only for runs of a specific workflow. Global webhooks fire for every workflow in your workspace. Every event payload includes a workflow_id field so you can route on your end. Register them in Settings → Webhooks by selecting “All Workflows” as the scope. For the full list of subscribable events you can set in event_types_subscribed, see the webhook schema in the Run API reference. Maintenance recovery flows emit the lifecycle events documented below, such as execution.requeued, execution.input_required, execution.password_updated, and the final terminal status.

execution.start

This event is sent once when the execution of the workflow starts. It returns a live view URL of the running browser agent embeddable as iframe.

{
  "event": "execution.start",
  "payload": {
    "session_id": "64355337-7561-45ec-82bc-b6266e11208c",
    "workflow_id": "745fdceb-53bf-4562-95dc-10495e303f0c",
    "live_view_url": "https://cyclone.cloudcruise.com/..."
  },
  "metadata": {
    "key1": "value1"
  },
  "timestamp": 1750068153,
  "expires_at": 1750068453
}

execution.step

This event is sent every time the workflow is executing an action like clicking on a button or filling out an input field.

{
    "payload": {
        "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8", 
        "workflow_id": "00b82d36-8243-4a95-a0ca-e64096226731",
        "current_step": "Type user name",
        "current_step_type": "INPUT_TEXT",
        "next_step": "Click Next",
        "next_step_type": "CLICK"
    },
    "metadata": {
        "key1": "value1"
    },
    "timestamp": 1724002463,
    "expires_at": 1724002763,
    "event": "execution.step"
}

execution.queued

This event is sent when a run is queued and waiting for an available worker.

{
  "event": "execution.queued",
  "payload": {
    "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8",
    "workflow_id": "00b82d36-8243-4a95-a0ca-e64096226731"
  },
  "metadata": {
    "key1": "value1"
  },
  "timestamp": 1724002463,
  "expires_at": 1724002763
}

execution.paused

This event is sent when a run is paused before execution (for example, when workflow-level or credential-level pause controls are active).

{
  "event": "execution.paused",
  "payload": {
    "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8",
    "workflow_id": "00b82d36-8243-4a95-a0ca-e64096226731",
    "pause_reasons": [
      {
        "resource_type": "workflow",
        "resource_id": "00b82d36-8243-4a95-a0ca-e64096226731",
        "reason": "Paused by workspace admin"
      }
    ]
  },
  "timestamp": 1724002463,
  "expires_at": 1724002763
}

execution.success

This event is sent once when the execution of the workflow has finished successfully. It includes the result data that is returned from the workflow.

{
    "payload": {
        "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8", 
        "workflow_id": "00b82d36-8243-4a95-a0ca-e64096226731",
        "data": {
            "your": "defined",
            "output": "datamodel",
        },
        "errors": [],
        "status": "execution.success",
        "file_urls": [],
        "input_variables": {
            "USER_NAME": "adrian"
        },
        "encrypted_variables": [
            "USER_NAME"
        ],
        "vault_entries": {
            "my_credential": {
                "USER_ID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "USER_ALIAS": "My Login",
                "USER_NAME": "encrypted_value",
                "PASSWORD": "encrypted_value",
                "DOMAIN": "https://example.com"
            }
        },
        "screenshot_urls": [
            {
                "signed_screenshot_url": "https://cloudcruise.com/screenshots/...",
                "signed_screenshot_url_expires": "2025-06-01T22:21:00.371579+00:00",
                "error_screenshot": false,
                "node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "node_display_name": "Click on login",
                "timestamp": "2025-05-25T22:21:00.371579+00:00"
            }
        ],
        "video_urls": [
            {
                "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8",
                "signed_screen_recording_url": "https://cloudcruise.com/videos/...",
                "signed_screen_recording_url_expires": "2025-06-01T22:21:00.371579+00:00",
                "timestamp": "2025-05-25T22:21:00.371579+00:00"
            }
        ]
    },
    "metadata": {
        "key1": "value1"
    },
    "timestamp": 1724002463,
    "expires_at": 1724002763,
    "event": "execution.success"
}

execution.failed

This event is sent once the execution of the workflow fails and contains information about the error.

{
    "payload": {
        "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8", 
        "workflow_id": "00b82d36-8243-4a95-a0ca-e64096226731",
        "data": {
            "your": "defined",
            "output": "datamodel",
        },
        "errors": [{
            "message": "The login failed. The website showed an error that the credentials are invalid.",
            "error_id": "c4c7d4fe-b00c-49d8-ab67-40808acea59c",
            "error_code": "E001: LOGIN_FAILED",
            "llm_error_category": "AUTHENTICATION_ERROR",
            "llm_error_sub_type": "INVALID_CREDENTIALS",
            "original_error": "Element not found: //button[@id='login-submit']",
            "full_url": "https://cloudcruise.com/login",
            "action_type": "CLICK",
            "action_display_name": "Click on login"
        }],
        "status": "execution.failed",
        "file_urls": [],
        "input_variables": {
            "$USER_NAME": "adrian"
        },
        "encrypted_variables": [
            "USER_NAME"
        ],
        "vault_entries": {
            "my_credential": {
                "USER_ID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "USER_ALIAS": "My Login",
                "USER_NAME": "encrypted_value",
                "PASSWORD": "encrypted_value",
                "DOMAIN": "https://example.com"
            }
        },
        "screenshot_urls": [
            {
                "signed_screenshot_url": "https://cloudcruise.com/screenshots/...",
                "signed_screenshot_url_expires": "2025-06-01T22:21:00.371579+00:00",
                "error_screenshot": true,
                "node_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "node_display_name": "Click on login",
                "timestamp": "2025-05-25T22:21:00.371579+00:00"
            }
        ],
        "video_urls": [
            {
                "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8",
                "signed_screen_recording_url": "https://cloudcruise.com/videos/...",
                "signed_screen_recording_url_expires": "2025-06-01T22:21:00.371579+00:00",
                "timestamp": "2025-05-25T22:21:00.371579+00:00"
            }
        ]
    },
    "timestamp": 1724002463,
    "expires_at": 1724002763,
    "event": "execution.failed"
}

The llm_error_category field contains an AI-generated categorization of the error type. This field may be null if AI analysis was not performed.The llm_error_sub_type field contains a more specific sub‑classification within the category. See the error classification matrix for all possible values. This field may be null if no sub‑type applies.The original_error field contains the raw technical runtime error message before any AI analysis. This is useful for debugging and differs from message field that contains the Maintenance Agent’s analysis.

execution.stopped

This event is sent when one or several workflow runs were cancelled. It respectively either contains session_id of the cancelled run or session_ids that contains all of the cancelled runs.Response for single run cancelled:

{
  "payload": {
    "message": "User interrupted workflow. Session was stopped.",
    "error_code": "INTERRUPTED-E0001",
    "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8", 
  },
  "timestamp": 1724002463,
  "expires_at": 1724002763,
  "event": "execution.stopped"
}

Response for multiple cancelled at once:

{
  "payload": {
    "message": "Execution was interrupted because another workflow was executed with the same credentials, but failed its login attempt. This is to prevent repeated incorrect login attempts.",
    "error_code": "INTERRUPTED-E0002",
    "session_causing_error": "60673dc6-92a1-428a-ba51-8c3f324daea8",
    "session_ids": ["60673dc6-92a1-428a-ba51-8c3f324daea8", "50673dc6-92a1-428a-ba51-8c3f324daea8"]
  },
  "metadata": {
        "key1": "value1"
  },
  "timestamp": 1724002463,
  "expires_at": 1724002763,
  "event": "execution.stopped"
}

execution.requeued

This event is sent when a failed run is automatically requeued for retry by the Maintenance Agent (e.g., after a SERVICE_UNAVAILABLE classification). See Service Unavailable Recovery for retry schedule details.

{
  "event": "execution.requeued",
  "payload": {
    "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8",
    "workflow_id": "00b82d36-8243-4a95-a0ca-e64096226731",
    "retry_attempt": 2,
    "max_retries": 10,
    "next_execution_time": "2026-05-26T23:30:00.000Z",
    "delay_ms": 1200000
  },
  "metadata": {
    "key1": "value1"
  },
  "timestamp": 1750068153,
  "expires_at": 1750068453
}

execution.input_required

This event is sent when a run pauses because incorrect input data was detected and the workflow is waiting for corrected values. Submit corrected fields using the Submit New Input Variables endpoint to resume execution.

{
  "event": "execution.input_required",
  "payload": {
    "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8",
    "input_variables": {
      "patient_id": "ABC-123"
    },
    "screenshot_url": "https://cloudcruise.com/screenshots/..."
  },
  "timestamp": 1724002463,
  "expires_at": 1724002763
}

execution.password_updated

This event is sent after an automated password recovery flow succeeds and CloudCruise updates the vault credential used by the run.

{
  "event": "execution.password_updated",
  "payload": {
    "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8",
    "workflow_id": "00b82d36-8243-4a95-a0ca-e64096226731"
  },
  "timestamp": 1724002463,
  "expires_at": 1724002763
}

screenshot.uploaded

This event is sent when the upload of the screenshot has finished.

Field	Description
`error_screenshot`	`true` when the screenshot was captured during an error.
`full_length_screenshot`	`true` when the screenshot is a full-page capture (scrolled and stitched). This happens for dedicated Screenshot nodes and error screenshots. Viewport-only captures set this to `false`.
`retry_index`	The retry attempt index for the run (0 = first attempt).

{
    "payload": {
        "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8",
        "screenshot_id": "6fdfad4a-3064-48cf-99f0-3d8d271f2c8e",
        "signed_screenshot_url": "https://cloudcruise.com/screenshots/...",
        "signed_screenshot_url_expires": "2024-08-25T17:35:00.432Z",
        "node_display_name": "Click on login",
        "node_id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
        "error_screenshot": true,
        "timestamp": "2024-08-30T17:35:00.432Z",
        "retry_index": 0,
        "full_length_screenshot": false,
        "metadata": {}
    },
    "metadata": {
        "key1": "value1"
    },
    "timestamp": 1724002463,
    "expires_at": 1724002763,
    "event": "screenshot.uploaded"
}

video.uploaded

This event is sent when the upload of the workflow video has finished.

{
    "payload": {
        "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8", 
        "signed_screen_recording_url": "https://cloudcruise.com/...",
        "signed_screen_recording_url_expires": "2025-06-01T22:21:00.371579+00:00",
        "timestamp": "2025-05-25T22:21:00.371579+00:00"
    },
    "metadata": {
        "key1": "value1"
    },
    "timestamp": 1724002463,
    "expires_at": 1724002763,
    "event": "video.uploaded"
}

file.uploaded

This event is sent when a file has been uploaded during workflow execution. The signed_file_url expiration is configurable per workspace (default: 7 days, range: 1 hour to 7 days). Configure this in your workspace settings.

{
    "payload": {
        "signed_file_url": "https://example.com/storage/v1/object/sign/files/123/456/example.zip?token=dummy-token",
        "file_name": "example_file.zip",
        "timestamp": "2024-03-20T12:00:00.000Z",
        "signed_file_url_expires": "2024-03-27T12:00:00.000Z",
        "metadata": {
            "key1": "value1"
        },
        "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8",
    },
    "timestamp": 1710936000,
    "expires_at": 1710936300,
    "event": "file.uploaded"
}

interaction.waiting

This event is sent when user input is required to continue the workflow.

{
    "payload": {
        "current_step": "Enter 2FA Code",
        "missing_properties": ["two_factor_code"],
        "message": "Please enter the 6-digit code sent to your phone",
        "session_id": "session-123",
        "workflow_id": "workflow-456",
        "expected_json_schema_datamodel": {
            "type": "object",
            "properties": {
                "two_factor_code": {
                    "type": "string",
                    "pattern": "^\\d{6}$",
                    "description": "6-digit verification code"
                }
            },
            "required": ["two_factor_code"]
        }
    },
    "timestamp": 1710936000,
    "expires_at": 1710936300,
    "event": "interaction.waiting"
}

interaction.failed

This event is sent when the user input was not provided in time or in a wrong format.

{
    "timestamp": 1724002463,
    "expires_at": 1724002763,
    "event": "interaction.failed"
}

interaction.finished

This event is sent when the user input was provided and the workflow continues.

{
    "payload": {
        "current_step": "Enter 2FA Code",
        "message": "Please enter the 6-digit code sent to your phone",
        "session_id": "session-123",
        "workflow_id": "workflow-456",
        "provided_input": {
            "two_factor_code": 123456
        },
        "expected_json_schema_datamodel": {
            "type": "object",
            "properties": {
                "two_factor_code": {
                    "type": "string",
                    "pattern": "^\\d{6}$",
                    "description": "6-digit verification code"
                }
            },
            "required": ["two_factor_code"]
        }       
    },
    "timestamp": 1724002463,
    "expires_at": 1724002763,
    "event": "interaction.finished"
}

Simply navigate to our settings page to get started.

Security

We sign webhook events with the secret you get when you register a webhook. We also add an expiry time. You can change the expiry time in the setting of the registered webhook. Here’s how we recommend to verify the message you receive from us:

Python
Javascript

import time
import hashlib
import hmac
import json

class VerificationError(Exception):
    """Custom exception to handle verification errors."""
    def __init__(self, message="Verification failed", status_code=400):
        super().__init__(message)
        self.status_code = status_code

def verify_hmac(received_data, received_signature, secret_key):
    # Ensure the received data is in bytes, necessary for HMAC
    if isinstance(received_data, str):
        received_data = received_data.encode()

    # Generate the HMAC new object with the secret key and SHA-256
    calculated_signature = hmac.new(secret_key.encode(), received_data, hashlib.sha256).hexdigest()

    # Safely compare the computed HMAC with the received HMAC
    return hmac.compare_digest(calculated_signature, received_signature)

# Extract signature from X-HMAC-Signature header, removing the 'Sha256=' prefix
# receivedData = await request.body()
# receivedSignature = request.headers.get('X-HMAC-Signature').split('=')[1]
# secretKey = your_secret_key
def verify_message(received_data, received_signature, secret_key):
    if not received_data:
        raise VerificationError("Received request without body", 400)
    
    try:
        data_json = json.loads(received_data.decode('utf-8'))
    except json.JSONDecodeError as e:
        raise VerificationError("Failed to decode json: " + str(e), 400)
    
    # Check if the expiration is sent
    expires_at = data_json.get("expires_at")
    if not expires_at:
        raise VerificationError("No expiration date sent", 400)

    # Verify HMAC first
    if not verify_hmac(received_data, received_signature, secret_key):
        raise VerificationError("Invalid HMAC signature.", 401)

    # Check if the message is not expired
    if time.time() > expires_at:
        raise VerificationError("Webhook message expired.", 400)

    return data_json

Install the package by following the TS/JS SDK overview.

import express from "express";
import { CloudCruise, VerificationError, WebhookEventType } from "cloudcruise";

const client = new CloudCruise({
    apiKey: process.env.CLOUDCRUISE_API_KEY,
    encryptionKey: process.env.CLOUDCRUISE_ENCRYPTION_KEY,
});

const app = express();

// Use a raw body parser so the SDK can verify the signature accurately
app.post(
    "/webhook",
    express.raw({ type: "application/json" }),
    (req, res) => {
        try {
            const signature = req.get("x-hmac-signature");
            const event = client.webhook.verifySignature(
                req.body,
                signature,
                process.env.CLOUDCRUISE_WEBHOOK_SECRET
            );

            switch (event.event) {
                case WebhookEventType.ExecutionSuccess:
                    console.log("Workflow completed successfully");
                    break;
                case WebhookEventType.ExecutionFailed:
                    console.log("Workflow failed");
                    break;
            }

            res.status(200).json({ status: "received" });
        } catch (error) {
            console.error("Invalid webhook", error);
            res.status(400).json({ error: "Invalid webhook" });
        }
    }
);

IP Allowlisting

All webhook requests from CloudCruise originate from the following static IP addresses. If your infrastructure requires IP-based filtering, add these to your allowlist:

164.71.220
191.200.70
236.26.110

Payload Size

A registration can be configured to omit input_variables from the payloads it receives. Turn on Exclude input variables from the payload in the webhook dialog in Settings → Webhooks, or send excludeInputVariables: true when creating or updating the webhook through the API. The field is then left out of every event delivered to that endpoint. Use it when you start runs with large inputs and your endpoint enforces a body-size limit — you already hold the inputs you sent. Other registrations are unaffected, and the run result from GET /runs/{session_id} still returns the inputs. excludeInputVariables is optional on update: leave it out and the endpoint keeps whatever setting it already has. The setting applies from the moment you turn it on. Events recorded before then were stored with input_variables included, and replaying one re-sends it as recorded — replay never rebuilds the payload. If you enable the option to get under a body-size limit, expect replays of earlier events to still exceed it.

Deliverability

CloudCruise automatically retries failed webhook deliveries up to 3 times (4 total attempts including the initial request) with exponential backoff delays between attempts. Each delivery attempt has a 5-second request timeout. Total delivery time depends on failure mode, so retries may complete quickly for immediate network errors or take longer for repeated timeouts.

Retry Conditions

A webhook delivery is retried when:

Network errors occur (connection timeout, DNS failure, etc.)
Server errors are returned (HTTP status codes 500 and above)
Request timeouts exceed 5 seconds

Webhooks are not retried for client errors (4xx status codes) as these typically indicate configuration issues that won’t resolve with retries.

Manual Replay

If webhooks still fail after automatic retries, you can manually replay them:

Dashboard: Navigate to the run detail view and trigger a resend
API: Send a POST request to https://api.cloudcruise.com/webhooks/{session_id}/replay

The replay endpoint will re-send all webhook events that were recorded for the given session.

Getting Started

Concepts

API Reference

SDK

Integrations

Security

IP Allowlisting

Payload Size

Deliverability

Retry Conditions

Manual Replay

​Security

​IP Allowlisting

​Payload Size

​Deliverability

​Retry Conditions

​Manual Replay

Security

IP Allowlisting

Payload Size

Deliverability

Retry Conditions

Manual Replay