API Keys & Webhooks

Connect your monitoring tools, CI/CD pipelines, and custom applications to Unthrottle. Use API keys for authentication and webhooks to trigger automations from external systems.

API Keys

Every webhook request requires an API key. Keys are UUIDs that authenticate requests and link them to your account. You can create multiple keys to track usage across different integrations—for example, separate keys for your monitoring system and CI/CD pipeline.

Creating an API Key

Navigate to Account → API Keys

Click Create API Key

Enter a descriptive name (e.g., "Nagios Alerts" or "GitHub Actions")

Copy the key immediately—we hash it for security and can't show it again

Store Keys Securely

Treat API keys like passwords. Store them in environment variables or a secrets manager, never in source code or public repositories.

Managing Keys

The API Keys page shows all your active keys with their names, creation dates, and when each was last used. This helps you identify unused keys that should be deleted and verify that your integrations are working correctly.

To rotate a key, create a new one, update your integration, verify it works, then delete the old key. This ensures zero downtime during rotation.

Webhooks

Webhooks let external systems trigger your automations via HTTP POST requests. When your monitoring system detects a host failure, when a deployment starts, or when any external event occurs—a webhook call can instantly adjust your circuit bandwidth.

Setting Up a Webhook

Create an automation and select Webhook as the trigger type
The system generates a unique webhook ID (a UUID) for this automation
Configure your external system to POST to the webhook URL with your API key
Test by calling the webhook manually with curl or your HTTP client

Webhook URL Format

POST /api/webhooks/{username}/{webhookId}

username The owner's account username

webhookId The UUID shown in your automation's webhook trigger settings

Authentication

Include your API key in the X-API-Key header. The key authenticates the request and determines which account's automations can be triggered—you can only trigger automations that belong to your account.

X-API-Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Example: Triggering a Webhook

This curl command fires a webhook automation. Replace the UUIDs and username with your actual API key, account username, and webhook ID:

curl -X POST \
     -H "X-API-Key: your-api-key-uuid" \
     -H "Content-Type: application/json" \
     -d '{"event": "deploy.started"}' \
     https://naas.lumen.com/api/webhooks/your-username/your-webhook-uuid

Routing the payload: The webhook receives the request body and emits it on a single output. Use a downstream If/Then node in your automation to branch on body fields — e.g. {{ webhook.body.event }} == "deploy.started". The previous onSuccess / onFailure URL path style is no longer used.

Integration Examples

Nagios / Icinga / Zabbix

Configure alert actions to POST a payload like {"status":"DOWN"} when a host fails and {"status":"UP"} when it recovers. Branch on the status field with an If/Then node — bandwidth increases automatically during outages.

GitHub Actions / GitLab CI

Add webhook calls to your deployment workflow. POST a payload containing the lifecycle phase (e.g. {"phase":"start"} or {"phase":"end"}) and route inside your automation to scale bandwidth around the deploy.

PagerDuty / Opsgenie

Use incident webhooks to trigger bandwidth changes when on-call engineers are paged. Ensure sufficient capacity during incident response without manual intervention.

Custom Scripts

Any system that can make HTTP requests can trigger webhooks. Use bash scripts, Python, Node.js, or any language to integrate bandwidth automation into your existing workflows.

Security Best Practices

Protecting API Keys

Environment variables—Store keys in $LUMEN_API_KEY or your CI/CD secrets, never hardcoded
One key per integration—If one system is compromised, revoke just that key
Regular rotation—Rotate keys quarterly or after any team member leaves
Monitor "last used"—Investigate keys with unexpected activity or keys that should be active but show no usage

Protecting Webhooks

HTTPS only—Never call webhooks over plain HTTP; credentials would be exposed
Limit access—Only systems that need to trigger automations should have the webhook ID
Audit the Events log—Webhook triggers are logged; review for unexpected patterns
Recreate if exposed—If a webhook ID leaks, delete the automation and create a new one with a fresh ID

Responding to a Security Incident

If you suspect an API key or webhook ID has been compromised: (1) immediately delete the affected key or automation, (2) create replacements, (3) update your integrations, and (4) review the Events log for unauthorized activity during the exposure window.