Async Webhooks

Async execution with webhooks is designed for very long-running tasks (>30 minutes) that would otherwise timeout. The execution happens asynchronously, and results are delivered to your webhook endpoint when complete.

Overview

Async webhook execution is perfect for:

ML model training (30+ minutes)
Large dataset processing
Video encoding/processing
Long-running simulations
Any task that exceeds normal timeout limits

Async webhook execution returns immediately with an execution_id. The agent executes code in the background and POSTs results to your callback URL when complete.

Basic Usage

Start async execution with a webhook callback:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Start async execution
response = sandbox.run_code_async(
    code='''
import time
print("Starting long task...")
time.sleep(600)  # 10 minutes
print("Task completed!")
''',
    callback_url='https://your-app.com/webhooks/HopX-complete',
    language='python',
    timeout=1800  # 30 minutes max
)

print(f"Execution ID: {response['execution_id']}")
print(f"Status: {response['status']}")
print(f"Callback URL: {response['callback_url']}")

sandbox.kill()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Start async execution
const response = await sandbox.runCodeAsync(
  `
import time
print("Starting long task...")
time.sleep(600)  # 10 minutes
print("Task completed!")
`,
  {
    callbackUrl: 'https://your-app.com/webhooks/HopX-complete',
    language: 'python',
    timeout: 1800  // 30 minutes max
  }
);

console.log(`Execution ID: ${response.executionId}`);
console.log(`Status: ${response.status}`);
console.log(`Callback URL: ${response.callbackUrl}`);

await sandbox.kill();

Webhook Callback

Your webhook endpoint will receive a POST request when execution completes:

Python (Flask)
JavaScript (Express)

from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhooks/HopX-complete', methods=['POST'])
def hopx_webhook():
    # Verify signature (if secret provided)
    signature = request.headers.get('X-HopX-Signature')
    timestamp = request.headers.get('X-HopX-Timestamp')
    
    # Verify signature if secret was provided
    # secret = 'your-webhook-secret'
    # expected_sig = hmac.new(
    #     secret.encode(),
    #     f"{timestamp}{request.data}".encode(),
    #     hashlib.sha256
    # ).hexdigest()
    # if signature != f"sha256={expected_sig}":
    #     return "Invalid signature", 401
    
    # Process webhook payload
    data = request.json
    execution_id = data['execution_id']
    status = data['status']
    stdout = data.get('stdout', '')
    stderr = data.get('stderr', '')
    exit_code = data.get('exit_code', 0)
    execution_time = data.get('execution_time', 0)
    
    print(f"Execution {execution_id} completed with status: {status}")
    print(f"Output: {stdout}")
    
    if status == 'completed':
        # Handle successful completion
        process_results(execution_id, stdout)
    else:
        # Handle failure
        handle_error(execution_id, stderr)
    
    return "OK", 200

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhooks/HopX-complete', (req, res) => {
  // Verify signature (if secret provided)
  const signature = req.headers['x-HopX-signature'];
  const timestamp = req.headers['x-HopX-timestamp'];
  
  // Verify signature if secret was provided
  // const secret = 'your-webhook-secret';
  // const expectedSig = crypto
  //   .createHmac('sha256', secret)
  //   .update(`${timestamp}${JSON.stringify(req.body)}`)
  //   .digest('hex');
  // if (signature !== `sha256=${expectedSig}`) {
  //   return res.status(401).send('Invalid signature');
  // }
  
  // Process webhook payload
  const { executionId, status, stdout, stderr, exitCode, executionTime } = req.body;
  
  console.log(`Execution ${executionId} completed with status: ${status}`);
  console.log(`Output: ${stdout}`);
  
  if (status === 'completed') {
    // Handle successful completion
    processResults(executionId, stdout);
  } else {
    // Handle failure
    handleError(executionId, stderr);
  }
  
  res.status(200).send('OK');
});

Signature Verification

Verify webhook signatures for security:

Python
JavaScript

from hopx_ai import Sandbox
import hmac
import hashlib

sandbox = Sandbox.create(template="code-interpreter")

# Start async execution with signature secret
response = sandbox.run_code_async(
    code='import time; time.sleep(600); print("Done")',
    callback_url='https://your-app.com/webhooks/HopX-complete',
    callback_signature_secret='your-webhook-secret-123',
    language='python'
)

print(f"Execution ID: {response['execution_id']}")

# In your webhook handler:
# signature = request.headers.get('X-HopX-Signature')
# timestamp = request.headers.get('X-HopX-Timestamp')
# body = request.data
# 
# expected = hmac.new(
#     'your-webhook-secret-123'.encode(),
#     f"{timestamp}{body}".encode(),
#     hashlib.sha256
# ).hexdigest()
# 
# if signature == f"sha256={expected}":
#     # Valid signature
#     pass

import { Sandbox } from '@hopx-ai/sdk';
import crypto from 'crypto';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Start async execution with signature secret
const response = await sandbox.runCodeAsync(
  'import time; time.sleep(600); print("Done")',
  {
    callbackUrl: 'https://your-app.com/webhooks/HopX-complete',
    callbackSignatureSecret: 'your-webhook-secret-123',
    language: 'python'
  }
);

console.log(`Execution ID: ${response.executionId}`);

// In your webhook handler:
// const signature = req.headers['x-HopX-signature'];
// const timestamp = req.headers['x-HopX-timestamp'];
// const body = JSON.stringify(req.body);
// 
// const expected = crypto
//   .createHmac('sha256', 'your-webhook-secret-123')
//   .update(`${timestamp}${body}`)
//   .digest('hex');
// 
// if (signature === `sha256=${expected}`) {
//   // Valid signature
// }

Custom Headers

Include custom headers in webhook callbacks:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Start async execution with custom headers
response = sandbox.run_code_async(
    code='import time; time.sleep(600); print("Done")',
    callback_url='https://your-app.com/webhooks/HopX-complete',
    callback_headers={
        'Authorization': 'Bearer your-api-token',
        'X-Custom-Header': 'custom-value'
    },
    language='python'
)

print(f"Execution ID: {response['execution_id']}")

# Your webhook will receive:
# POST https://your-app.com/webhooks/HopX-complete
# Authorization: Bearer your-api-token
# X-Custom-Header: custom-value
# X-HopX-Signature: sha256=...
# X-HopX-Timestamp: 1698765432

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Start async execution with custom headers
const response = await sandbox.runCodeAsync(
  'import time; time.sleep(600); print("Done")',
  {
    callbackUrl: 'https://your-app.com/webhooks/HopX-complete',
    callbackHeaders: {
      'Authorization': 'Bearer your-api-token',
      'X-Custom-Header': 'custom-value'
    },
    language: 'python'
  }
);

console.log(`Execution ID: ${response.executionId}`);

// Your webhook will receive:
// POST https://your-app.com/webhooks/HopX-complete
// Authorization: Bearer your-api-token
// X-Custom-Header: custom-value
// X-HopX-Signature: sha256=...
// X-HopX-Timestamp: 1698765432

Complete Example

Here’s a complete example with ML model training:

Python
JavaScript

from hopx_ai import Sandbox

sandbox = Sandbox.create(template="code-interpreter")

# Start ML training with async webhook
response = sandbox.run_code_async(
    code='''
import time
import random

print("Starting ML model training...")
print("Epoch 1/10...")
time.sleep(60)

for epoch in range(2, 11):
    loss = random.uniform(0.1, 0.5)
    accuracy = random.uniform(0.8, 0.95)
    print(f"Epoch {epoch}/10 - Loss: {loss:.4f}, Accuracy: {accuracy:.4f}")
    time.sleep(60)

print("Training completed!")
print("Model saved to /workspace/model.pkl")
''',
    callback_url='https://your-app.com/webhooks/ml-training-complete',
    callback_headers={
        'Authorization': 'Bearer ml-api-token',
        'X-Training-ID': 'training-123'
    },
    callback_signature_secret='ml-webhook-secret',
    language='python',
    timeout=3600,  # 1 hour
    env={
        'WANDB_API_KEY': 'your-wandb-key',
        'HF_TOKEN': 'your-huggingface-token'
    }
)

print(f"✅ Training started")
print(f"Execution ID: {response['execution_id']}")
print(f"Status: {response['status']}")
print(f"Results will be posted to: {response['callback_url']}")

# Your webhook will receive results when training completes
sandbox.kill()

import { Sandbox } from '@hopx-ai/sdk';

const sandbox = await Sandbox.create({ template: 'code-interpreter' });

// Start ML training with async webhook
const response = await sandbox.runCodeAsync(
  `
import time
import random

print("Starting ML model training...")
print("Epoch 1/10...")
time.sleep(60)

for epoch in range(2, 11):
    loss = random.uniform(0.1, 0.5)
    accuracy = random.uniform(0.8, 0.95)
    print(f"Epoch {epoch}/10 - Loss: {loss:.4f}, Accuracy: {accuracy:.4f}")
    time.sleep(60)

print("Training completed!")
print("Model saved to /workspace/model.pkl")
`,
  {
    callbackUrl: 'https://your-app.com/webhooks/ml-training-complete',
    callbackHeaders: {
      'Authorization': 'Bearer ml-api-token',
      'X-Training-ID': 'training-123'
    },
    callbackSignatureSecret: 'ml-webhook-secret',
    language: 'python',
    timeout: 3600,  // 1 hour
    env: {
      WANDB_API_KEY: 'your-wandb-key',
      HF_TOKEN: 'your-huggingface-token'
    }
  }
);

console.log('✅ Training started');
console.log(`Execution ID: ${response.executionId}`);
console.log(`Status: ${response.status}`);
console.log(`Results will be posted to: ${response.callbackUrl}`);

// Your webhook will receive results when training completes
await sandbox.kill();

Webhook Payload

The webhook payload structure:

{
  "execution_id": "abc123",
  "status": "completed",
  "stdout": "Task output...",
  "stderr": "",
  "exit_code": 0,
  "execution_time": 600.123
}

Headers:

X-HopX-Signature: HMAC-SHA256 signature (if secret provided)
X-HopX-Timestamp: Unix timestamp
Custom headers from callback_headers

Best Practices

1. Always Verify Signatures

Use callback_signature_secret and verify signatures in your webhook handler to ensure requests are authentic.

2. Handle Timeouts

Set appropriate timeouts based on expected execution time. Default is 30 minutes, max is typically 1 hour.

3. Use Custom Headers

Include authentication tokens or identifiers in callback_headers for secure webhook processing.

4. Handle Both Success and Failure

Check the status field in webhook payloads to handle both successful completions and failures.

5. Store Execution IDs

Store execution_id when starting async execution to correlate webhook callbacks with your records.

Synchronous Execution - Basic code execution
Background Execution - Long-running tasks
Streaming Execution - Real-time output streaming
SDK: sandbox.run_code_async() - Python SDK method
API: POST /execute/async - VM Agent API endpoint
CLI Code Execution - Execute code from CLI

Next Steps

Learn about Background Execution for shorter tasks
Explore Process Management for monitoring
Review Synchronous Execution for immediate results

Home

Get Started

Sandboxes

Code Execution

Filesystem

Commands

Environment Variables

Templates

Desktop Automation

Terminal

Observability

Cache

Overview

Basic Usage

Webhook Callback

Signature Verification

Custom Headers

Complete Example

Webhook Payload

Best Practices

Next Steps

​Overview

​Basic Usage

​Webhook Callback

​Signature Verification

​Custom Headers

​Complete Example

​Webhook Payload

​Best Practices

​Related

​Next Steps

Overview

Basic Usage

Webhook Callback

Signature Verification

Custom Headers

Complete Example

Webhook Payload

Best Practices

Related

Next Steps