Integrations Guide (Webhooks + JSON Payloads)

Hypertag is designed to fit into systems you already use. A Hyper tag sends an HTTP request to your endpoint and can include a JSON payload, so you can trigger automation without rebuilding your stack.

Why this is easy to integrate

• Hypertag sends standard webhooks (`POST` requests).
• Payloads are plain JSON and can be parsed by any modern platform.
• You can reuse existing endpoints, queues, workflow tools, and observability systems.
• No SDK lock-in is required for basic integration.

Basic Hyper tag setup

When creating or editing a Hyper tag, configure:

• `webhook`: your target HTTPS endpoint
• `payload`: optional JSON object with the fields your workflow needs

Example payload:

{
  "source": "hypertag",
  "eventType": "scan",
  "tagId": "tag_42",
  "location": "warehouse-a",
  "action": "open_work_order",
  "priority": "high"
}

n8n integration example

Use this pattern to trigger an n8n workflow when a Hyper tag is scanned.

1. Create an n8n webhook trigger

• In n8n, create a new workflow.
• Add a `Webhook` node as the trigger.
• Method: `POST`
• Path: something like `hypertag-scan`
• Copy the Production URL from the Webhook node.

2. Configure the Hyper tag in Hypertag

• Set `webhook` to the n8n Production URL.
• Add a payload your workflow will use, for example:

{
  "source": "hypertag",
  "eventType": "scan",
  "tagId": "asset-pump-17",
  "assetType": "pump",
  "site": "plant-3",
  "requestedBy": "qr-scan"
}

3. Build downstream nodes in n8n

After the Webhook node, add any combination of:

• `IF` node for routing by `assetType` or `site`
• `HTTP Request` node to call internal APIs
• `Slack`/`Email` node for notifications
• `Notion`, `Airtable`, `Google Sheets`, or DB nodes for logging

Common expression examples in n8n:

• `{{$json["tagId"]}}`
• `{{$json["site"]}}`
• `{{$json["eventType"]}}`

4. Activate and test

• Activate the n8n workflow.
• Activate your Hyper tag in Hypertag.
• Scan the QR code and confirm the n8n execution appears in the workflow runs.

Recommended payload design

• Keep field names stable and predictable.
• Use small, explicit payloads instead of deeply nested objects unless needed.
• Include identifiers (`tagId`, `site`, `eventType`) for deterministic branching.
• Version payload contracts when you introduce breaking field changes.

Reliability and security checklist

• Use HTTPS webhook endpoints.
• Add authentication at the receiving endpoint when possible.
• Validate incoming payload shape in your workflow.
• Handle non-2xx responses and retries in downstream systems.
• Log execution outcomes for fast diagnosis.

Example use cases

• Create a maintenance ticket when an equipment tag is scanned.
• Trigger an inventory check and notify operations.
• Send scan context into BI pipelines for audit and reporting.

Hypertag works as an ingestion and trigger layer, so you can orchestrate behavior in tools your teams already trust.