Webhook Ingestion

Webhooks allow external systems to push data into Inspire’s DataPool in real time via HTTP POST requests. This is the fastest way to get data into Inspire — updates arrive the instant they are sent.

Webhook Endpoint

Each webhook connector provides a unique endpoint URL:


POST https://inspire.yourcompany.com/api/webhook/{stream-name}

Authentication

All webhook requests must include the connector’s ingest key:


curl -X POST https://inspire.yourcompany.com/api/webhook/sales \
  -H "Authorization: Bearer ik_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "region": "North",
    "sales": 142000,
    "target": 130000
  }'

Request Format

Single item

Send a JSON object to create or update a single item:


{
  "region": "North",
  "sales": 142000,
  "target": 130000,
  "updated": "2026-04-06T10:30:00Z"
}

Multiple items

Send a JSON array to upsert multiple items in one request:


[
  { "region": "North", "sales": 142000, "target": 130000 },
  { "region": "South", "sales": 98000, "target": 110000 },
  { "region": "East", "sales": 156000, "target": 140000 }
]

Nested JSON flattening

Nested JSON objects are automatically flattened using dot notation:


{
  "location": {
    "city": "London",
    "country": "UK"
  },
  "metrics": {
    "footfall": 1250,
    "dwell_time": 3.5
  }
}

Results in DataPool fields: location.city, location.country, metrics.footfall, metrics.dwell_time.

Response

Status	Meaning
`202 Accepted`	Data received and queued for processing
`400 Bad Request`	Invalid JSON payload
`401 Unauthorized`	Missing or invalid ingest key
`413 Payload Too Large`	Request body exceeds 1 MB limit
`429 Too Many Requests`	Rate limit exceeded

Webhook ingestion returns 202 Accepted immediately. Data processing happens asynchronously. The data typically appears in the DataPool within 100ms.

Custom ID Fields

By default, items are identified by their position in the payload. To specify a custom ID field, set the X-Item-Key header:


curl -X POST https://inspire.yourcompany.com/api/webhook/sales \
  -H "Authorization: Bearer ik_live_abc123..." \
  -H "Content-Type: application/json" \
  -H "X-Item-Key: region" \
  -d '{ "region": "North", "sales": 142000 }'

This ensures that subsequent updates with the same region value update the existing item rather than creating a new one.

Idempotency

Include an Idempotency-Key header to prevent duplicate processing:


curl -X POST https://inspire.yourcompany.com/api/webhook/sales \
  -H "Authorization: Bearer ik_live_abc123..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sale-north-20260406-1030" \
  -d '{ "region": "North", "sales": 142000 }'

Requests with the same idempotency key within 24 hours are accepted but not reprocessed.

Integration Examples

From a CI/CD pipeline


# Post build metrics after deployment
curl -X POST $INSPIRE_WEBHOOK_URL \
  -H "Authorization: Bearer $INSPIRE_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"build\": \"$BUILD_NUMBER\",
    \"status\": \"deployed\",
    \"duration_seconds\": $BUILD_DURATION,
    \"timestamp\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"
  }"

From a Node.js application


const response = await fetch('https://inspire.yourcompany.com/api/webhook/app-metrics', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ik_live_abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    active_users: 1250,
    requests_per_minute: 340,
    error_rate: 0.02,
  }),
})