> ## Documentation Index
> Fetch the complete documentation index at: https://utexo-e7ed9bd0-update.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

The Utexo Cloud supports webhooks to notify users about events in their nodes.

## Adding a Webhook Endpoint

You can add a webhook endpoint to your node by editing the node's settings:

1. Navigate to your node and click **Settings**.
2. Locate the field named **Webhook URL**.
3. Enter the endpoint where you'd like to send requests.
4. Note down your public key from the settings, as it will be used to verify requests.

## Adding a Webhook When Creating a Node

When creating a new node via the API, you can provide a Webhook URL in the settings. This allows to send webhook notifications to your specified endpoint. You can update this URL later through the node's settings if needed.

## Retrieve the Public Key

To verify webhook requests, retrieve the public key from: [https://cloud-api.thunderstack.org/api/webhook-public-key](https://cloud-api.thunderstack.org/api/webhook-public-key)

This public key is used to validate the `X-ThunderStack-Signature` header included in each webhook event.

## How Webhooks Work

When an event is triggered, ThunderStack sends a POST request to your webhook endpoint. The request includes:

1. A **JSON payload** with details about the event.
2. A header named `X-ThunderStack-Signature` containing a digital signature created with ThunderStack's private key.

## Verification Steps

1. **Validate the Signature**: Use the public key to verify the `X-ThunderStack-Signature` header.
2. **Validate the Payload**: Ensure the `nodeId` in the payload matches the expected node or endpoint.

**Payload Schema** The JSON payload sent to your webhook endpoint has the following structure:

```json copy theme={null}
{
  "eventType": "NODE_STATUS_UPDATED",
  "eventTimestamp": "2026-04-16T12:00:00Z",
  "details": {
    "nodeId": "your-node-id",
    "status": "RUNNING"
  },
  "nodeId": "your-node-id"
}
```

## Status Values

* **RUNNING**: The node is running.
* **STARTING**: The node is starting.
* **PAUSED**: The node is paused.
* **FAILED**: The node has failed.
* **IN\_PROGRESS**: An operation is currently in progress.

## Security Considerations

1. **Use HTTPS**: Always use HTTPS for your webhook endpoint to ensure data security during transit.
2. **Signature Verification**: Validate the `X-ThunderStack-Signature` header using the public key.
3. **Payload Validation**: Ensure the `nodeId` field matches the expected node.

This ensures secure, reliable, and real-time notifications for your nodes.

**Example Webhook Handler**

Here’s an example of a webhook handler in JavaScript/TypeScript:

```javascript copy theme={null}
import * as crypto from 'crypto';

// Main function to handle webhook events
export async function handleWebhookEvent(request) {
  // Extract the signature and body
  const receivedSignature = request.headers['x-thunderstack-signature'] || request.headers['X-ThunderStack-Signature'];
  const body = typeof request.body === 'string' ? request.body : JSON.stringify(request.body);

  // Retrieve the public key for signature verification
  const publicKey = 'YOUR_PUBLIC_KEY_HERE';

  // Create a verifier to validate the signature using the public key
  const verify = crypto.createVerify('RSA-SHA256');
  verify.update(body);
  verify.end();

  // Validate the signature
  const isValid = verify.verify(publicKey, receivedSignature, 'base64');
  if (!isValid) {
    console.error('Invalid signature');
    return {
      statusCode: 403,
      body: JSON.stringify({ message: 'Forbidden - Invalid Signature' })
    };
  }

  // Handle the validated webhook event here
  console.log('Valid webhook event received');
  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Webhook event processed successfully' })
  };
}
```