Webhooks

You can register webhooks for each workflow to receive events. Here are the different events you can subscribe to:

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.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",
            "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 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"
}

screenshot.uploaded

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

{
    "payload": {
        "session_id": "60673dc6-92a1-428a-ba51-8c3f324daea8", 
        "error_screenshot": true,
        "created_at": "2024-08-30T17:35:00.432Z",
        "node_display_name": "Click on login",
        "screenshot_id": "6fdfad4a-3064-48cf-99f0-3d8d271f2c8e",
        "signed_screenshot_url": "https://cloudcruise.com/screenshots/...",
        "signed_screenshot_url_expires": "2024-08-25T17:35:00.432Z",
    },
    "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

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

Deliverability

Retry Conditions

Manual Replay

Getting Started

Concepts

API Reference

SDK

Integrations

​Security

​IP Allowlisting

​Deliverability

​Retry Conditions

​Manual Replay

Security

IP Allowlisting

Deliverability

Retry Conditions

Manual Replay