Skip to main content

Quick Start

Set up your first webhook in 5 minutes. By the end of this guide, you will have a working endpoint receiving real-time events from Infodeck, plus a first event filter to keep the traffic scoped.

Prerequisites​

  • An Infodeck API key or Bearer token (Authentication Guide)
  • A publicly accessible HTTPS endpoint
  • Your organization ID (found in Settings > Organization)
No server yet?

Use webhook.site to get a free test URL instantly -- no code required. Open the site, copy your unique URL, and use it as the endpoint URL below. You will see every incoming request with full headers and body in real time.

Step 1: Create a Webhook​

Register your endpoint with Infodeck, specify which events you want to receive, and add an optional filter.

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",
    "events": ["asset.created", "asset.status.changed"],
    "description": "Production asset sync",
    "filtering": {
      "mode": "include",
      "criteria": {
        "locationId": ["loc_hq_01"]
      }
    }
  }'

Response:

{
  "data": {
    "webhookId": "whk_k7x9m2nq",
    "url": "https://your-server.com/webhooks",
    "events": ["asset.created", "asset.status.changed"],
    "description": "Production asset sync",
    "filtering": {
      "mode": "include",
      "criteria": {
        "locationId": ["loc_hq_01"]
      }
    },
    "status": "active",
    "signingSecret": "whsec_a1b2c3d4e5f6g7h8i9j0...",
    "createdAt": 1771911526000
  },
  "requestId": "req_abc123"
}
danger

Save the signingSecret immediately. It is only returned once at creation time. You will need it to verify incoming webhook signatures.

Prefer the dashboard? Go to Settings > Webhooks > + Add Endpoint, paste your URL, select events, fill in Event filters if needed, and click Create Endpoint. The signing secret is shown once in a modal - copy it before closing.

Step 2: Set Up Your Endpoint​

Create a minimal HTTP handler that receives webhook events. The key rule: return 200 quickly, process asynchronously.

Node.js (Express)​

// NOTE: This example omits signature verification for brevity.
// NEVER deploy without verification — see Step 4 below.
const express = require('express');
const app = express();

app.post('/webhooks', express.raw({ type: 'application/json', limit: '1mb' }), (req, res) => {
  const event = JSON.parse(req.body);
  console.log('Received:', event.type, event.id);

  // Process the event
  switch (event.type) {
    case 'asset.created':
      // Handle new asset
      break;
    case 'asset.status.changed':
      // Handle asset state change
      break;
  }

  // Return 200 quickly -- process async if needed
  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Webhook endpoint listening on port 3000'));

Python (Flask)​

# NOTE: This example omits signature verification for brevity.
# NEVER deploy without verification — see Step 4 below.
# When adding verification, switch to request.get_data() for the raw body.
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks', methods=['POST'])
def handle_webhook():
    event = request.get_json()
    print(f"Received: {event['type']} {event['id']}")

    if event['type'] == 'asset.created':
        # Handle new asset
        pass
    elif event['type'] == 'asset.status.changed':
        # Handle asset state change
        pass

    return jsonify(received=True), 200
info

For local development, expose your local server with ngrok:

ngrok http 3000

Then use the ngrok HTTPS URL (e.g., https://abc123.ngrok.io/webhooks) as your webhook URL.

Step 3: Send a Test Event​

Verify your endpoint works by sending a test event from the API.

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

Your endpoint will receive a webhook.test event:

{
  "id": "evt_test_xyz789",
  "type": "webhook.test",
  "organizationId": "o-xxxx",
  "created": 1771911600,
  "data": {
    "object": {
      "message": "This is a test webhook event from Infodeck"
    }
  },
  "isTest": true,
  "livemode": false
}

Check your server logs (or webhook.site) to confirm receipt.

info

Test events ignore webhook filters. They are intended to confirm connectivity, not matching behavior.

Dashboard alternative: On the Webhooks list page, click the play icon on your webhook row to send a test event.

Step 4: Verify the Signature​

Every webhook delivery includes an x-infodeck-signature header. Always verify this signature in production to ensure the request genuinely came from Infodeck.

Here is a quick verification check in Node.js:

const crypto = require('crypto');

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

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

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your Express handler:
app.post('/webhooks', express.raw({ type: 'application/json', limit: '1mb' }), (req, res) => {
  const sig = req.headers['x-infodeck-signature'];
  const isValid = verifyWebhookSignature(req.body.toString(), sig, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Safe to process
  const event = JSON.parse(req.body);
  res.status(200).json({ received: true });
});

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

Step 5: Go Live​

Once your test event is verified, you are ready for production. Here is a checklist:

  • Endpoint returns 200 within 30 seconds
  • Signature verification is enabled
  • Signing secret is stored securely (environment variable, not source code)
  • Event processing is idempotent (handles duplicates safely)
  • Error handling and logging are in place

Next Steps​

Was this page helpful?