Integrations

Klaxon integrates with workflow automation tools like n8n, Node-RED, and any system that can make HTTP calls. It replaces simple notification services like ntfy with interactive forms, acknowledgements, and rich responses.

n8n community nodes

The repo ships three first-party n8n nodes under packages/n8n-nodes-klaxon (published to npm as @ottercoders/n8n-nodes-klaxon):

Node	Purpose
KlaxonNotify	Send a one-way notification
KlaxonAsk	Send a form question and wait for the answer (blocking workflow step with configurable timeout)
KlaxonTrigger	Webhook trigger fired on item events (item.created, item.answered, item.dismissed)

Install via the n8n Community Nodes UI (@ottercoders/n8n-nodes-klaxon) or pin to a version in package.json if you're self-hosting. Credentials use a standard bearer token created in Settings → API keys on the Klaxon dashboard.

The Human-in-the-Loop Pattern

Automation workflow
  │
  ├─ POST to Klaxon (create item with form + callback_url)
  │
  ├─ User receives push notification on phone
  │
  ├─ User answers the form
  │
  └─ Klaxon POSTs response to callback_url → workflow continues

The callback_url field is the key: when an item with a callback URL is answered, dismissed, or acknowledged, Klaxon automatically POSTs the result back to that URL.

n8n Integration

Setup

1. Create a webhook in Klaxon (Settings → Webhooks → Create):

   • Name: n8n
   • URL: your n8n instance URL (not used for inbound — just for identification)

2. Note the webhook secret token — this authenticates inbound requests.

Example: Deployment Approval

n8n Workflow:

1. Webhook Trigger node (waits for callback from Klaxon)
2. HTTP Request node → Klaxon inbound webhook:

POST https://klaxon.sh/api/webhooks/inbound/YOUR_SECRET_TOKEN

{
  "title": "Approve deployment to production?",
  "message": "v2.3.0 is ready. 47 changes, 3 migrations.",
  "level": "warning",
  "callback_url": "https://n8n.example.com/webhook/TRIGGER_UUID",
  "form": {
    "id": "deploy-approval",
    "fields": [
      {
        "id": "approved",
        "type": "yesno",
        "label": "Approve this deployment?",
        "required": true,
        "yes_label": "Deploy",
        "no_label": "Reject"
      },
      {
        "id": "notes",
        "type": "textarea",
        "label": "Notes (optional)"
      }
    ]
  },
  "metadata": {
    "version": "v2.3.0",
    "commit": "abc123"
  }
}

3. User receives push notification → opens Klaxon → sees form → taps "Deploy"

4. Klaxon POSTs to the callback URL:

{
  "item_id": "550e8400-...",
  "status": "answered",
  "response": {
    "approved": true,
    "notes": "LGTM, ship it"
  },
  "answered_at": "2026-04-14T10:30:00Z",
  "metadata": {
    "version": "v2.3.0",
    "commit": "abc123"
  },
  "title": "Approve deployment to production?"
}

5. n8n Webhook Trigger receives the response → IF node checks response.approved → continues to deploy or rollback.

Example: Incident Triage

{
  "title": "High CPU on db-primary",
  "message": "CPU at 95% for 10 minutes. Auto-scaling triggered.",
  "level": "error",
  "callback_url": "https://n8n.example.com/webhook/incident-response",
  "form": {
    "id": "incident-triage",
    "fields": [
      {
        "id": "severity",
        "type": "select",
        "label": "Severity",
        "required": true,
        "options": [
          { "value": "p1", "label": "P1 - Critical" },
          { "value": "p2", "label": "P2 - High" },
          { "value": "p3", "label": "P3 - Medium" }
        ]
      },
      {
        "id": "action",
        "type": "radio",
        "label": "Immediate action",
        "options": [
          { "value": "scale_up", "label": "Scale up instances" },
          { "value": "restart", "label": "Rolling restart" },
          { "value": "investigate", "label": "Investigate only" }
        ]
      }
    ]
  }
}

Callback Payload

When an item with a callback_url changes status, Klaxon POSTs:

{
  "item_id": "uuid",
  "status": "answered | dismissed | open",
  "response": { ... form values ... } | null,
  "answered_at": "ISO 8601" | null,
  "metadata": { ... original metadata ... },
  "title": "original title"
}

The callback fires on:

• Answer: user submits form response
• Dismiss: user dismisses the item
• Ack: user acknowledges the item
• Archive/restore: item lifecycle changes

Generic Webhook Integration

Any tool that can make HTTP requests works with Klaxon:

# Create an interactive notification
curl -X POST https://klaxon.sh/api/webhooks/inbound/TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Disk usage above 90%",
    "level": "warning",
    "callback_url": "https://your-automation.example.com/handle-response",
    "form": {
      "id": "disk-action",
      "fields": [
        {"id": "action", "type": "yesno", "label": "Clean up old logs?", "required": true}
      ]
    }
  }'

REST API (Authenticated)

For direct API integration with a bearer token:

# Create item with form + callback
curl -X POST https://klaxon.sh/api/items \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Approve budget increase",
    "form": { ... },
    "callback_url": "https://your-app.com/callbacks/klaxon"
  }'

MCP (Agent Integration)

Agents can also set callback URLs via MCP tools:

{
  "method": "tools/call",
  "params": {
    "name": "klaxon.ask",
    "arguments": {
      "title": "Review PR #42?",
      "form": { ... },
      "callback_url": "https://..."
    }
  }
}