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

Webhook Security

Signature Verification

Each webhook request includes a signature in the x-webhook-signature header. This signature should be used to verify the authenticity of the webhook payload.

Header Name: x-webhook-signature
Format: sha256=<hex_signature>
Example: sha256=91b43462bbdb16c914df335e8936f169647225287e21b0db7ac1f05146c9e43

Verifying Webhooks

To ensure the webhook came from our service and wasn't tampered with:

Get the signature from the x-webhook-signature header
Calculate the HMAC SHA-256 of the raw request body using your webhook secret
Compare your calculated signature with the one in the header

For security reasons, you should:

Always verify the signature before processing webhooks
Use constant-time comparison when checking signatures
Keep your webhook secret secure and never expose it

Event Types

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

Possible event types:

EVENT_TYPE_MACHINE_CREATED
EVENT_TYPE_MACHINE_UPDATED
EVENT_TYPE_MACHINE_REMOVED
EVENT_TYPE_DEPLOYMENT_CREATED
EVENT_TYPE_DEPLOYMENT_UPDATED
EVENT_TYPE_DEPLOYMENT_STOPPED

Machine Events

`EVENT_TYPE_MACHINE_CREATED`

event_type: 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": "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"
}

`EVENT_TYPE_MACHINE_UPDATED`

event_type: 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": "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"
}

`EVENT_TYPE_MACHINE_REMOVED`

event_type: 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": "EVENT_TYPE_MACHINE_REMOVED",
  "data": {
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be"
  },
  "timestamp": "2024-10-28T12:10:00Z"
}

Deployment Events

`EVENT_TYPE_DEPLOYMENT_CREATED`

event_type: EVENT_TYPE_DEPLOYMENT_CREATED
Description: Triggered when a new deployment is initiated.
Data Fields:
- Full deployment data, including container status.

Example Payload

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

`EVENT_TYPE_DEPLOYMENT_UPDATED`

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

Example Payload

{
  "version": "1.0",
  "event_id": "345e4567-e89b-12d3-a456-426614174004",
  "event_type": "EVENT_TYPE_DEPLOYMENT_UPDATED",
  "data": {
    "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "CONTAINER_STATUS_STATUS_RUNNING",
    "fail_reason": {
      "code": "",
      "message": ""
    },
    "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"
}

`EVENT_TYPE_DEPLOYMENT_STOPPED`

event_type: 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 container status.

Example Payload

{
  "version": "1.0",
  "event_id": "456e4567-e89b-12d3-a456-426614174005",
  "event_type": "EVENT_TYPE_DEPLOYMENT_STOPPED",
  "data": {
    "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "CONTAINER_STATUS_STATUS_STOPPED",
    "fail_reason": {
      "code": "",
      "message": ""
    },
    "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 (EVENT_TYPE_MACHINE_CREATED, EVENT_TYPE_MACHINE_UPDATED, EVENT_TYPE_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: EVENT_TYPE_MACHINE_UPDATED

{
  "event_id": "987e4567-e89b-12d3-a456-426614174000",
  "event_type": "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": "string",
    "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 container lifecycle, allowing vendors to understand the current condition of a deployment and respond accordingly.

Deployment Container Status Values

Status	Description
`CONTAINER_STATUS_UNSPECIFIED`	The deployment status is unspecified.
`CONTAINER_STATUS_STATUS_PENDING`	The deployment is in the process of starting up and preparing for job execution. This includes loading software, applying configurations, or performing initial checks.
`CONTAINER_STATUS_STATUS_STOPPING`	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.
`CONTAINER_STATUS_STATUS_STOPPED`	The deployment is powered off and not executing any jobs. This status is applicable to deployments that have been stopped by a user or finished executing a job.
`CONTAINER_STATUS_STATUS_FAILED`	The deployment has encountered an error preventing it from executing jobs properly. This status necessitates intervention to resolve the underlying issue.
`CONTAINER_STATUS_STATUS_RUNNING`	The deployment is actively executing a job. This status indicates the deployment is fully operational and performing the tasks it was deployed for.

Usage in Webhook Payloads

The status field in deployment-related events (EVENT_TYPE_DEPLOYMENT_CREATED, EVENT_TYPE_DEPLOYMENT_UPDATED, EVENT_TYPE_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: EVENT_TYPE_DEPLOYMENT_UPDATED

{
  "event_id": "345e4567-e89b-12d3-a456-426614174004",
  "event_type": "EVENT_TYPE_DEPLOYMENT_UPDATED",
  "data": {
    "deployment_id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
    "machine_id": "d63d2545-af1a-42e8-9d4b-2f36b064f0be",
    "status": "CONTAINER_STATUS_STATUS_RUNNING",
    "fail_reason": {
      "code": "",
      "message": ""
    },
    "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​

Webhook Security​

Signature Verification​

Verifying Webhooks​

Event Types​

Possible event types:​

Machine Events​

EVENT_TYPE_MACHINE_CREATED​

Example Payload​

EVENT_TYPE_MACHINE_UPDATED​

Example Payload​

EVENT_TYPE_MACHINE_REMOVED​

Example Payload​

Deployment Events​

EVENT_TYPE_DEPLOYMENT_CREATED​

Example Payload​

EVENT_TYPE_DEPLOYMENT_UPDATED​

Example Payload​

EVENT_TYPE_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 Container Status Values​

Usage in Webhook Payloads​

General Webhook Structure

Webhook Security

Signature Verification

Verifying Webhooks

Event Types

Possible event types:

Machine Events

`EVENT_TYPE_MACHINE_CREATED`

Example Payload

`EVENT_TYPE_MACHINE_UPDATED`

Example Payload

`EVENT_TYPE_MACHINE_REMOVED`

Example Payload

Deployment Events

`EVENT_TYPE_DEPLOYMENT_CREATED`

Example Payload

`EVENT_TYPE_DEPLOYMENT_UPDATED`

Example Payload

`EVENT_TYPE_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 Container Status Values

Usage in Webhook Payloads