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
- Navigate to your node page and click Settings.
- Locate the Webhook URL field.
- Enter the HTTPS endpoint where you want to receive events.
- 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"
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.
- Use HTTPS — Your webhook endpoint must use HTTPS to protect data in transit.
- Verify the signature — Validate the
X-ThunderStack-Signature header using the public key on every request.
- Validate the node ID — Confirm the
nodeId in the payload matches the node you expect.