Webhook Management

Webhook Integration Guide

Overview

Subscribe to receive real-time weight updates from weighbridges via HTTP webhooks. When a weighbridge reports a new weight, your endpoint will receive a POST request with the weight data.

Webhook Payload

Your endpoint will receive POST requests with the following JSON payload:

{
  "event": "weight.updated",
  "weighbridgeId": "WB-001",
  "weight": 26420.5,
  "unit": "kg",
  "isStable": true,
  "timestamp": "2026-01-30T06:45:00.000Z"
}

Headers

Header	Description
Content-Type	application/json
X-Webhook-Signature	HMAC-SHA256 signature (if secret configured)
X-Webhook-Timestamp	Unix timestamp of the request

Signature Verification

If you provide a secret when creating a subscription, all webhook requests will include a signature header for verification:

X-Webhook-Signature: sha256=<signature>

To verify the signature:

1. Get the raw request body
2. Compute HMAC-SHA256 using your secret
3. Compare with the signature in the header

Example (Node.js)

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Example (C#)

using System.Security.Cryptography;
using System.Text;

bool VerifySignature(string payload, string signature, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    var expected = "sha256=" + Convert.ToHexString(hash).ToLower();
    return signature == expected;
}

Retry Policy

Failed webhook deliveries are retried up to 3 times with exponential backoff:

• 1st retry: 5 seconds
• 2nd retry: 30 seconds
• 3rd retry: 2 minutes

A delivery is considered failed if:

• Connection timeout (30 seconds)
• HTTP status code is not 2xx
• Network error

API Endpoints

Method	Endpoint	Description
GET	/api/subscriptions	List all subscriptions
GET	/api/subscriptions/{id}	Get subscription by ID
POST	/api/subscriptions	Create subscription
DELETE	/api/subscriptions/{id}	Delete subscription

Create Subscription (API)

POST /api/subscriptions
Content-Type: application/json

{
  "weighbridgeId": "WB-001",
  "callbackUrl": "https://your-server.com/webhook",
  "secret": "your-secret-key"
}

Response

{
  "id": "sub_abc123",
  "weighbridgeId": "WB-001",
  "callbackUrl": "https://your-server.com/webhook",
  "isActive": true,
  "createdAt": "2026-01-30T06:45:00.000Z"
}

Best Practices

• Respond quickly: Return a 2xx response within 30 seconds
• Process asynchronously: Queue webhook data for background processing
• Verify signatures: Always verify webhook signatures in production
• Handle duplicates: Use idempotency keys to handle potential retries
• Use HTTPS: Always use HTTPS for your callback URL