Helios emits webhook events to notify your system of execution lifecycle changes in real time.
Webhooks allow you to react to execution updates without polling the API.

Webhook Overview

Webhooks are HTTP callbacks sent to a URL you configure.
Each event represents a state change or notable condition during execution.

Events are delivered asynchronously and are at-least-once.

Event Types

Helios emits the following core event categories.

Execution Events

Emitted when a new execution is created.

{
  "type": "execution.created",
  "data": {
    "executionId": "hx_88421a",
    "asset": "USDC",
    "amount": "4500",
    "fromChain": "ethereum",
    "toChain": "arbitrum"
  }
}

Status Updates

Emitted when an execution changes state.

{
  "type": "execution.updated",
  "data": {
    "executionId": "hx_88421a",
    "status": "pending"
  }
}

Possible status values mirror the Execution API:
created, pending, executed, failed.

Failure & Rollback Events

Emitted when an execution fails or aborts safely.

{
  "type": "execution.failed",
  "data": {
    "executionId": "hx_88421a",
    "reason": "RISK_THRESHOLD_EXCEEDED"
  }
}

Failure events are final and will not be followed by recovery events unless a new execution is created.

Webhook Payload Structure

All webhook payloads follow a consistent structure.

{
  "id": "evt_102938",
  "type": "execution.updated",
  "createdAt": 1737048129,
  "data": { }
}

Event IDs are unique and can be used for idempotency.

Webhook Security

Helios signs all webhook payloads to verify authenticity.

Each webhook includes a signature header:

X-Helios-Signature: ab34f9

Verifying Signatures (Node.js)

import crypto from "crypto";

const expectedSignature = crypto
  .createHmac("sha256", process.env.HELIOS_WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

if (signature !== expectedSignature) {
  throw new Error("Invalid webhook signature");
}

Always verify signatures before processing events.

Retries & Delivery

If your endpoint responds with a non-2xx status, Helios retries delivery.

Retry behavior:

• Exponential backoff

• Limited retry window

• Event order not guaranteed across retries

Webhook endpoints should be idempotent.

Idempotency

Use the event id to prevent duplicate processing.

if (processedEvents.has(event.id)) {
  return;
}

Helios may deliver the same event more than once.