API Keys & Webhooks

Connect your monitoring tools, CI/CD pipelines, and custom applications to Lumen NaaS. 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/{webhookId}/{path}

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

path onSuccess triggers the success branch, onFailure triggers the failure branch

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 triggers the success branch of an automation. Replace the UUIDs with your actual API key and webhook ID:

curl -X POST \
     -H "X-API-Key: your-api-key-uuid" \
     https://naas.lumen.com/api/webhooks/your-webhook-uuid/onSuccess

Success vs Failure Paths: Use onSuccess when conditions are favorable (e.g., high traffic detected, deployment starting) and onFailure when reverting (e.g., traffic normalized, deployment complete). The path names map directly to your automation's success/failure branches.

Integration Examples

Nagios / Icinga / Zabbix

Configure alert actions to call onSuccess when a host goes DOWN and onFailure when it recovers. Bandwidth increases automatically during outages to handle failover traffic.

GitHub Actions / GitLab CI

Add webhook calls to your deployment workflow. Call onSuccess before deploying large assets, onFailure after deployment completes to restore normal bandwidth.

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.