Webhook Configuration

Configure TTN webhooks to automatically send water quality sensor data to your JalRakshak.AI backend for processing and storage.

Webhooks

API Integration

Real-time Data

MongoDB

What are Webhooks?

Webhooks are HTTP callbacks that automatically send data from TTN to your application when events occur (like receiving sensor uplinks). The JalRakshak.AI webhook endpoint receives, decodes, and stores water quality readings in MongoDB.

Data Flow:

1. Sensor→2. LoRaWAN→3. TTN→4. Webhook→5. MongoDB→6. Dashboard

Setting Up Webhooks

Important

Ensure your JalRakshak.AI application is deployed and publicly accessible before configuring webhooks. For local development, you can use the SmartPark relay as a bridge.

Webhook Configuration Steps

Navigate to Webhooks

In your TTN application, go to "Integrations" → "Webhooks"

Add Webhook

Click "+ Add webhook" → "Custom webhook"

Configure Webhook ID

Webhook ID:

jalrakshak-uplink

Set Base URL

Production (after Vercel deploy):

https://jalrakshak-ai-dualcore.vercel.app/api/webhook

Local Development (use SmartPark relay as bridge):

https://iot-smart-park.vercel.app/api/ttn/jalrakshak-ai

The relay forwards data to your localhost. Useful during development when your server isn't publicly accessible.

Enable Uplink Message

Under Enabled messages, tick Uplink message only.

Uplink message

Optional: Secure with Shared Secret

For production, secure your webhook with a shared secret:

Add custom header in TTN:

Header: X-TTN-Secret

Value: your_secret_value

Set the same value in Vercel environment:

TTN_WEBHOOK_SECRET=your_secret_value

Leave both unset for open access (fine for hackathon / development).

Webhook API Endpoint

POST

/api/webhook

Receives TTN uplink data, decodes payload, and stores readings in MongoDB.

Expected Payload Structure:

{
  "end_device_ids": {
    "device_id": "jalrakshak-node-01",
    "application_ids": {
      "application_id": "jalrakshak-ai"
    }
  },
  "uplink_message": {
    "decoded_payload": {
      "temperature": 25.3,
      "tds": 312,
      "ph": 7.21
    },
    "rx_metadata": [
      {
        "gateway_ids": {
          "gateway_id": "your-gateway"
        },
        "rssi": -85,
        "snr": 9.5
      }
    ]
  }
}

Backend Processing:

Extracts device ID and decoded sensor readings

Generates turbidity (placeholder) and calculates conductivity (TDS × 2)

Creates/updates Device document with latest reading timestamp

Stores Reading document in MongoDB with all parameters

Dashboard automatically fetches and displays new data

Testing & Verification

After configuring the webhook, verify it's working correctly:

1Check Webhook Status in TTN Console

• Navigate to your webhook configuration

• Click "Test" to send a test payload

• Verify you receive a 200 OK response

2Check Database for New Readings

• Visit /api/sensor-data in your browser

• Verify readings are being stored with correct device ID

• Check timestamps are current

3Verify Dashboard Updates

• Power on your ESP32 sensor and wait for transmission

• Check if device card appears on dashboard

• Verify sensor readings display correctly

• Confirm AI predictions generate successfully

4Monitor Serial Output (ESP32)

• Open Arduino Serial Monitor (115200 baud)

• Verify JOIN_ACCEPT message received

• Confirm uplink transmissions every 60 seconds

• Check sensor readings before transmission

Troubleshooting Common Issues

❌ Webhook returns 404 or 500 errors

Possible causes:

Webhook URL is incorrect or server is not deployed
API route doesn't exist or has errors
Server is not publicly accessible

Solutions:

Verify URL matches your deployed application
Check Vercel deployment logs for errors
Test endpoint manually with curl or Postman

❌ Data received but not stored in database

Possible causes:

MongoDB connection string is incorrect
Payload structure doesn't match expected format
TTN payload decoder not configured

Solutions:

Check DATABASE_URL in environment variables
Verify payload decoder is set up correctly in TTN
Test database connection with /api/db-test

❌ Dashboard not showing new data

Possible causes:

Dashboard polling interval too long
Device ID mismatch between TTN and expected format
Data stuck in relay (for local development)

Solutions:

Manually refresh dashboard page
Verify device ID format matches exactly
Check if MongoDB has recent readings for this device
Clear browser cache and reload

Need More Help?

Check TTN Console → Application → Live data to see real-time messages from your devices. This is the best way to debug webhook and payload issues.

🎉 Setup Complete!

Your JalRakshak.AI system is now fully configured and ready to monitor water quality.

System Ready:

TTN Application & Device Configured

Payload Decoder Active

Webhooks Forwarding Data

Dashboard Displaying Readings

View Dashboard Back to Docs Home

TTN Setup