Integration Guide

Build a working integration with Infodeck from zero. By the end of this guide, your system will be reading operational data from Infodeck and receiving real-time event notifications whenever something changes.

This guide is for developers connecting an external system (ERP, BMS, BI tool, or custom application) to Infodeck. If you are a non-developer admin setting up webhooks from the dashboard, see Webhook Settings.

---

What You Will Build

Your System                          Infodeck
┌──────────────────┐                ┌──────────────────┐
│                  │── API Key ────>│                  │
│  Read data       │<── JSON ──────│  Work Orders     │
│  Write data      │── POST ──────>│  Assets          │
│                  │                │  Locations       │
│                  │<── Webhook ───│  IoT Sensors     │
│  Receive events  │── 200 OK ────>│  Bookings        │
└──────────────────┘                └──────────────────┘

Two channels work together:

Channel	Direction	Purpose
API calls	You → Infodeck	Read and write operational data on demand
Webhooks	Infodeck → You	Receive real-time notifications when something changes

---

Before You Start

You will need:

• An Infodeck account on Professional or Enterprise plan
• Organization Admin or Owner role (to create API keys and webhooks)
• A server or endpoint that can receive HTTPS POST requests (for webhooks)
• Your Organization ID — found in Settings → Company Profile (the URL also contains it: app.infodeck.io/{your-org-url}/...)

---

Step 1: Create an API Key

API keys let your system authenticate with Infodeck without a login flow. One key per integration is the recommended practice.

1. Go to Settings → API Keys
2. Click Create API Key
3. Give it a descriptive name (e.g., "SAP Connector", "Power BI Dashboard", "BMS Sync")
4. Copy the key immediately — it is shown only once

Your key looks like this:

idt_live_4JtUAvekCZ5lktALZBiVyiKcwtsdbfM7

Store it securely in an environment variable or secrets manager. Never commit it to source code.

---

Step 2: Make Your First API Call

Test your key by fetching your organization's work orders:

curl https://app.infodeck.io/api/v2/organizations/{orgId}/work-orders \
  -H "X-Api-Key: idt_live_4JtUAvekCZ5lktALZBiVyiKcwtsdbfM7"

Node.js:

const response = await fetch(
  `https://app.infodeck.io/api/v2/organizations/${ORG_ID}/work-orders`,
  { headers: { 'X-Api-Key': process.env.INFODECK_API_KEY } }
);
const { data } = await response.json();
console.log(`Found ${data.length} work orders`);

Python:

import requests
import os

response = requests.get(
    f"https://app.infodeck.io/api/v2/organizations/{ORG_ID}/work-orders",
    headers={"X-Api-Key": os.environ["INFODECK_API_KEY"]}
)
work_orders = response.json()["data"]
print(f"Found {len(work_orders)} work orders")

If you get a 200 response with JSON data, your API key is working. If you get 401 or 403, check that your key is correct and your plan includes API access.

---

Step 3: Register a Webhook

Now set up real-time notifications. Webhooks require a Bearer token (not an API key) because they control where your organization's data is sent — a security-sensitive operation that should only be done by authenticated users.

Why Bearer token for webhooks?

API keys are designed for reading and writing operational data. Webhook management controls data flow out of your organization, so it requires stronger authentication. An admin sets up the webhook once, and your integration receives events using the signing secret.

Option A: Via the Dashboard (Recommended for Most Teams)

1. Go to Settings → Webhooks
2. Click Add Endpoint
3. Enter your HTTPS endpoint URL
4. Select the events you want (e.g., workorder.status.changed, asset.telemetry.updated)
5. Click Create
6. Copy the signing secret — it is shown only once

Option B: Via the API

curl -X POST https://app.infodeck.io/api/v2/organizations/{orgId}/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/infodeck",
    "events": ["workorder.status.changed", "asset.telemetry.updated"],
    "description": "BMS integration - work orders and sensors"
  }'

The response includes a signingSecret — store it immediately. You will need it to verify incoming webhook deliveries.

---

Step 4: Handle Incoming Webhooks

When something changes in Infodeck, your endpoint receives an HTTPS POST with a JSON payload:

{
  "id": "evt_abc123",
  "type": "workorder.status.changed",
  "organizationId": "o-xxxx",
  "created": 1771911526,
  "data": {
    "object": {
      "workOrderId": "wo_456def",
      "status": "complete",
      "previousStatus": "in_progress"
    }
  }
}

Your handler should:

1. Return 200 immediately — Infodeck waits up to 30 seconds. If your processing takes longer, queue it and respond first.
2. Verify the signature — Confirm the request came from Infodeck (Step 5).
3. Process idempotently — The same event may be delivered more than once. Use the id field to deduplicate.

Node.js (Express):

app.post('/webhooks/infodeck', express.raw({ type: 'application/json' }), (req, res) => {
  // Return 200 immediately
  res.status(200).json({ received: true });

  const event = JSON.parse(req.body);

  switch (event.type) {
    case 'workorder.status.changed':
      syncWorkOrderStatus(event.data.object);
      break;
    case 'asset.telemetry.updated':
      updateSensorReading(event.data.object);
      break;
  }
});

Python (Flask):

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/infodeck', methods=['POST'])
def handle_webhook():
    event = request.get_json()

    if event['type'] == 'workorder.status.changed':
        sync_work_order_status(event['data']['object'])
    elif event['type'] == 'asset.telemetry.updated':
        update_sensor_reading(event['data']['object'])

    return jsonify(received=True), 200

---

Step 5: Verify Webhook Signatures

Every delivery includes an x-infodeck-signature header. Always verify this in production to confirm the request came from Infodeck and was not tampered with.

The header format:

x-infodeck-signature: t=1771911526,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Verification logic:

1. Extract the timestamp (t) and signature (v1) from the header
2. Construct the signed payload: {timestamp}.{raw_request_body}
3. Compute HMAC-SHA256 using your signing secret
4. Compare with constant-time comparison
5. Reject if the timestamp is more than 5 minutes old (replay protection)

const crypto = require('crypto');

function verifySignature(rawBody, header, secret) {
  const [tPart, v1Part] = header.split(',');
  const timestamp = tPart.split('=')[1];
  const signature = v1Part.split('=')[1];

  const signedPayload = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );

  // Reject old timestamps (replay protection)
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) return false;

  return isValid;
}

For full examples in Python and Go, see Webhook Security.

---

Step 6: Test the Full Flow

Before going live, verify the complete round trip:

Test the API

# List work orders
curl https://app.infodeck.io/api/v2/organizations/{orgId}/work-orders \
  -H "X-Api-Key: {your-api-key}"

# Get a specific asset
curl https://app.infodeck.io/api/v2/organizations/{orgId}/assets/{assetId} \
  -H "X-Api-Key: {your-api-key}"

Test the Webhook

# Send a test event
curl -X POST https://app.infodeck.io/api/v2/organizations/{orgId}/webhooks/{webhookId}/test \
  -H "Authorization: Bearer {token}"

Your endpoint receives a webhook.test event. Check your logs to confirm:

• The request arrived
• The signature verified correctly
• Your handler processed the event

Check Delivery Logs

If a test event did not arrive, check the delivery logs:

curl https://app.infodeck.io/api/v2/organizations/{orgId}/webhooks/{webhookId}/deliveries \
  -H "Authorization: Bearer {token}"

This shows every delivery attempt with status codes, response times, and failure reasons.

---

Step 7: Go Live Checklist

Before putting your integration into production:

API Side:

• API key stored in environment variable or secrets manager
• Error handling for 401, 403, 429, and 5xx responses
• Pagination implemented for list endpoints (see Pagination)
• Rate limit awareness (1,000 requests/minute per key)

Webhook Side:

• Endpoint returns 200 within 30 seconds
• Signature verification enabled with constant-time comparison
• Signing secret stored securely (not in source code)
• Event processing is idempotent (handles duplicate deliveries)
• Failed processing is queued for retry, not dropped
• HTTPS enforced on your endpoint

Operations:

• Monitoring and alerting for failed webhook deliveries
• Secret rotation plan (recommended every 90 days)
• One API key per integration (enables targeted revocation)

---

Understanding the Two Secrets

This is the most common point of confusion for new integrators:

	API Key	Webhook Signing Secret
You use it to	Call Infodeck's API	Verify Infodeck's webhook deliveries
Created in	Settings → API Keys	Settings → Webhooks (or via API)
Sent in	X-Api-Key header on YOUR requests	x-infodeck-signature header on OUR deliveries
Who verifies	Infodeck verifies your key	You verify our signature
If compromised	Revoke the API key, create a new one	Rotate the signing secret
Expires	Never (until revoked)	Never (until rotated)

They serve different purposes and travel in opposite directions. Your integration uses both.

---

Common Integration Patterns

ERP Sync (SAP, Oracle, NetSuite)

Subscribe to workorder.completed and workorder.status.changed. When a work order is completed, push the labor hours and parts used to your ERP for cost allocation.

BMS Integration (Building Management System)

Subscribe to asset.telemetry.updated for real-time sensor data. Use the API to fetch asset details and map sensor readings to your BMS points.

BI Dashboard (Power BI, Tableau)

Use the API to pull work order metrics, SLA compliance data, and asset health scores on a schedule. Webhooks are optional here — scheduled API calls work well for dashboards that refresh every 15 minutes.

Ticketing System (ServiceNow, Jira)

Subscribe to workorder.created. When a new work order appears in Infodeck, create a corresponding ticket in your ticketing system. Use the API to sync status changes back.

---

Troubleshooting

Problem	Likely Cause	Solution
401 Invalid API key	Key format wrong or key not found	Check key starts with idt_live_ and was copied completely
403 API access requires Professional plan	Plan does not include API access	Upgrade to Professional or Enterprise
429 Too many requests	Exceeded 1,000 requests/minute	Add backoff and retry logic
Webhook not arriving	Endpoint unreachable or returning non-200	Check delivery logs, verify URL is public HTTPS
Signature verification failing	Using parsed JSON instead of raw body	Use raw request body for HMAC computation
Duplicate events	Normal — webhooks guarantee at-least-once delivery	Use event id field to deduplicate

---

Next Steps

• API Authentication — Detailed API key and JWT reference
• REST API Reference — Full endpoint documentation
• Webhook Management API — CRUD endpoints for webhook subscriptions
• Event Catalog — Payload reference for every event type
• Webhook Security — Signature verification deep dive
• Best Practices — Production patterns for reliability