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

# Webhooks

> Receive real-time event notifications from your Utexo Cloud RLN nodes.

## Overview

Utexo Cloud supports webhooks to notify your application about events occurring in your RLN nodes. When an event is triggered, ThunderStack sends a `POST` request to your configured endpoint with a JSON payload and a cryptographic signature header for verification.

## Setting Up a Webhook

### Option 1: Via Node Settings

1. Navigate to your node page and click **Settings**.
2. Locate the **Webhook URL** field.
3. Enter the HTTPS endpoint where you want to receive events.
4. Save the settings. Your public key for signature verification is shown in the same section.

### Option 2: Via API at Node Creation

When creating a node via the Cloud API, include `webhookUrl` in the `settings` object:

```bash theme={null}
curl -s \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-node","network":"regtest","settings":{"webhookUrl":"https://example.com/webhooks/thunderstack"}}' \
  "https://cloud-api.thunderstack.org/api/nodes"
```

## How Webhooks Work

When a node state changes or an operation completes, ThunderStack sends a `POST` request to your endpoint including:

* A **JSON payload** with the event data and `nodeId`
* A **`X-ThunderStack-Signature` header** containing a cryptographic signature

## Node Status Values

Webhook events reflect the following node status transitions:

| Status        | Description                           |
| ------------- | ------------------------------------- |
| `RUNNING`     | Node is fully operational             |
| `STARTING`    | Node is starting up                   |
| `PAUSED`      | Node has been paused                  |
| `FAILED`      | Node encountered an error             |
| `IN_PROGRESS` | An operation is currently in progress |

## Verifying Webhook Signatures

All webhook requests include a `X-ThunderStack-Signature` header that should be validated to confirm authenticity.

### Step 1: Retrieve the Public Key

```bash theme={null}
curl -s \
  -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \
  "https://cloud-api.thunderstack.org/api/webhook-public-key"
```

This returns the public key used to sign all webhook payloads from your account.

### Step 2: Validate the Signature

Use the public key to verify the `X-ThunderStack-Signature` header on each incoming request.

### Step 3: Validate the Payload

Ensure the `nodeId` in the payload matches the expected node to prevent spoofing.

## Security Best Practices

<Warning>
  Always verify the `X-ThunderStack-Signature` header before processing any webhook payload.
</Warning>

1. **Use HTTPS** — Your webhook endpoint must use HTTPS to protect data in transit.
2. **Verify the signature** — Validate the `X-ThunderStack-Signature` header using the public key on every request.
3. **Validate the node ID** — Confirm the `nodeId` in the payload matches the node you expect.