Webhook payload

This documentation describes the structure of the webhook payloads for various event_type values that can be sent to the callback URL provided by vendors. Each event contains a dynamic data field, whose structure varies depending on the event_type. The standard structure for each webhook includes:

event_id: Unique identifier for the event.
event_type: Specifies the type of event that triggered the webhook.
data: Object containing event-specific data. The structure of this object depends on the value of event_type (detailed in the sections below).
timestamp: ISO 8601 timestamp when the event was generated.

General Webhook Structure

{
  "version": "1.0",
  "event_id": "123e4567-e89b-12d3-a456-426614174001",
  "event_type": "event_type_value",
  "data": { /* Event-specific data */ },
  "timestamp": "2024-10-28T12:05:00Z"
}

Event Types

The following sections detail each supported event_type and the corresponding structure of the data field.

Machine Events

`machine_created`

event_type: machine_created
Description: Triggered when a new machine listing is added.
Data Fields:
- Full machine data as described below.

Example Payload

{
  "version": "1.0",
  "event_id": "123e4567-e89b-12d3-a456-426614174001",
  "event_type": "machine_created",
  "data": {
    "machine_id" : "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "string" // Possible values: "available", "rented", "inactive"
    "machine_prices": [
      {
        "id": "5b10ce4d-9772-4487-bcc0-c7440e633370",
        "amount": "1",
        "currency": "BTC"
      }
    ],
    "metadata": {
      "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
      "geo_location": {
        "country": "USA",
        "city": "San Francisco"
      },
      "cuda_version": "12.1"
    },
    "hardware_specs": { /* detailed hardware specs */ },
    "network_info": { /* detailed network info */ }
  },
  "timestamp": "2024-10-28T12:05:00Z"
}

`machine_updated`

event_type: machine_updated
Description: Triggered when details of an existing machine listing are updated.
Data Fields:
- Full machine data as described below.

Example Payload

{
  "version": "1.0",
  "event_id": "987e4567-e89b-12d3-a456-426614174000",
  "event_type": "machine_updated",
  "data": {
    "machine_id" : "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "string" // Possible values: "available", "rented", "inactive"
    "machine_prices": [
      {
        "id": "3f189ae6-f831-4509-a018-1bce5cde48ee",
        "amount": "5",
        "currency": "USD"
      }
    ],
    "metadata": { /* machine metadata */ },
    "hardware_specs": { /* detailed hardware specs */ },
    "network_info": { /* detailed network info */ }
  },
  "timestamp": "2024-10-28T12:05:00Z"
}

`machine_removed`

event_type: machine_removed
Description: Triggered when a machine listing is removed.
Data Fields:
- machine_id: Unique identifier of the removed machine.

Example Payload

{
  "version": "1.0",
  "event_id": "543e4567-e89b-12d3-a456-426614174002",
  "event_type": "machine_removed",
  "data": {
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be"
  },
  "timestamp": "2024-10-28T12:10:00Z"
}

Deployment Events

`deployment_created`

event_type: deployment_created
Description: Triggered when a new deployment is initiated.
Data Fields:
- Full deployment data as described below.

Example Payload

{
  "version": "1.0",
  "event_id": "234e4567-e89b-12d3-a456-426614174003",
  "event_type": "deployment_created",
  "data": {
    "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "STATUS_INITIALIZING",
    "metadata": { /* deployment metadata */ },
    "connection_info": { /* connection details */ }
  },
  "timestamp": "2024-10-28T12:15:00Z"
}

`deployment_updated`

event_type: deployment_updated
Description: Triggered when the status or details of an existing deployment change.
Data Fields:
- Full deployment data, including status updates.

Example Payload

{
  "version": "1.0",
  "event_id": "345e4567-e89b-12d3-a456-426614174004",
  "event_type": "deployment_updated",
  "data": {
    "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "STATUS_RUNNING",
    "fail_reason": {
      "code": 0,
      "message": "No errors"
    },
    "connection_info": {
      "ssh": {
        "direct": "ssh [email protected] -p 2222",
        "proxy": "ssh -o 'proxycommand socat - PROXY:ssh1.hiveon.ai:%h:%p,proxyport=5002' ${deploymentUUID}@hiveon.ai"
      }
    }
  },
  "timestamp": "2024-10-28T12:20:00Z"
}

`deployment_stopped`

event_type: deployment_stopped
Description: Triggered when a deployment is stopped, either manually or due to an error.
Data Fields:
- Deployment information, including the final status.

Example Payload

{
  "version": "1.0",
  "event_id": "456e4567-e89b-12d3-a456-426614174005",
  "event_type": "deployment_stopped",
  "data": {
    "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "STATUS_STOPPED",
    "fail_reason": {
      "code": 1001,
      "message": "Shutdown requested by user"
    },
    "metadata": { /* optional metadata */ }
  },
  "timestamp": "2024-10-28T12:25:00Z"
}

Machine Data Structure

The data field for machine events will use the following JSON schema:

{
  "status": "string",
  "machine_prices": [ /* pricing details */ ],
  "metadata": { /* metadata details */ },
  "hardware_specs": { /* detailed hardware specs */ },
  "network_info": { /* network details */ }
}

Machine Status Events

The following section details the available MachineListingStatus values that can be included in machine-related webhook events. Each status represents a different state of a machine listing, allowing vendors to understand the availability and operational condition of a machine.

Machine Status Values

Status	Description
`available`	The machine listing is available for use and can be rented or deployed. This status indicates that the machine is operational and ready to be assigned to tasks.
`unavailable`	The machine listing is currently not available for use. This can be due to maintenance, temporary issues, or administrative action.
`rented`	The machine listing has been rented and is currently in use. While in this status, the machine cannot be assigned to other tasks or rented by other users.

Usage in Webhook Payloads

The status field in machine-related events (machine_created, machine_updated, machine_removed) will use one of the MachineListingStatus values. The status allows the vendor to track the availability of a machine and take appropriate actions based on its current state.

Example Payload: machine_updated

{
  "event_id": "987e4567-e89b-12d3-a456-426614174000",
  "event_type": "machine_updated",
  "data": {
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "rented",
    "machine_prices": [
      {
        "id": "3f189ae6-f831-4509-a018-1bce5cde48ee",
        "amount": "5",
        "currency": "USD"
      }
    ],
    "metadata": { /* machine metadata */ },
    "hardware_specs": { /* detailed hardware specs */ },
    "network_info": { /* detailed network info */ }
  },
  "timestamp": "2024-10-28T12:05:00Z"
}

Recommendations for Handling Machine Status

Monitoring Availability: Continuously monitor machines with an available status to ensure they remain in good working order and are ready for use.
Usage Tracking: When machines transition to rented, vendors should track their usage and performance, ensuring that any issues can be addressed swiftly without affecting the ongoing tasks.
Out from listing: If machine is out from listing the vendor will receive a webhook and the machine will dissapear from the listings.

Deployment Data Structure

The data field for deployment events will use the following JSON schema:

{
  "deployment_id": "string",
  "machine_id": "string",
  "status": "string",
  "fail_reason": {
    "code": "integer",
    "message": "string"
  },
  "metadata": { /* optional metadata */ },
  "connection_info": { /* connection and port forwarding details */ }
}

Deployment Status Events

The following section details the available DeploymentStatus values that can be included in deployment-related webhook events. Each status represents a different state of the deployment lifecycle, allowing vendors to understand the current condition of a deployment and respond accordingly.

Deployment Status Values

Status	Description
`idle`	The deployment is not currently executing any jobs but is powered on and ready to perform tasks. This status is applicable to deployments awaiting job execution.
`initializing`	The deployment is in the process of starting up and preparing for job execution. This includes loading software, applying configurations, or performing initial checks.
`running`	The deployment is actively executing a job. This status indicates the deployment is fully operational and performing the tasks it was deployed for.
`shutting_down`	The deployment is in the process of shutting down from an operational state. This could be due to job completion, a user-initiated shutdown, or preparation for maintenance.
`error`	The deployment has encountered an error preventing it from executing jobs properly. This status necessitates intervention to resolve the underlying issue.
`stopped`	The deployment is stopped and not performing any operations. This can occur if a deployment was terminated, canceled, or shut down after completing its tasks.

Usage in Webhook Payloads

The status field in deployment-related events (deployment_created, deployment_updated, deployment_stopped) will use one of the DeploymentStatus values. The status allows the vendor to track the state of the deployment and take appropriate actions or log relevant information.

Example Payload: deployment_updated

{
  "event_id": "345e4567-e89b-12d3-a456-426614174004",
  "event_type": "deployment_updated",
  "data": {
    "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "running",
    "fail_reason": {
      "code": 0,
      "message": "No errors"
    },
    "connection_info": {
      "ssh": {
        "direct": "ssh [email protected] -p 2222",
        "proxy": "ssh -o 'proxycommand socat - PROXY:ssh1.hiveon.ai:%h:%p,proxyport=5002' ${deploymentUUID}@hiveon.ai"
      }
    }
  },
  "timestamp": "2024-10-28T12:20:00Z"
}

Webhook payload

General Webhook Structure​

Event Types​

Machine Events​

machine_created​

Example Payload​

machine_updated​

Example Payload​

machine_removed​

Example Payload​

Deployment Events​

deployment_created​

Example Payload​

deployment_updated​

Example Payload​

deployment_stopped​

Example Payload​

Machine Data Structure​

Machine Status Events​

Machine Status Values​

Usage in Webhook Payloads​

Recommendations for Handling Machine Status​

Deployment Data Structure​

Deployment Status Events​

Deployment Status Values​

Usage in Webhook Payloads​

General Webhook Structure

Event Types

Machine Events

`machine_created`

Example Payload

`machine_updated`

Example Payload

`machine_removed`

Example Payload

Deployment Events

`deployment_created`

Example Payload

`deployment_updated`

Example Payload

`deployment_stopped`

Example Payload

Machine Data Structure

Machine Status Events

Machine Status Values

Usage in Webhook Payloads

Recommendations for Handling Machine Status

Deployment Data Structure

Deployment Status Events

Deployment Status Values

Usage in Webhook Payloads