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:

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

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

Always verify the X-ThunderStack-Signature header before processing any webhook payload.

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.