Data Forwarders

Overview

Forwarders deliver device data to external systems. Two built-in strategies are available:

1. PostData webhook: push each measurement to your HTTP endpoint.
2. SaveToMongoDB: mirror data into a custom MongoDB collection.

Both forwarders are organization-wide singletons and configure how Yanji IoT Cloud relays data to external destinations.

• Base Paths:
  • /api/v2/forwarders/post/
  • /api/v2/forwarders/mongodb/

Endpoint Summary

Method	Path	Purpose
GET	/forwarders/post/	Retrieve webhook configuration
PUT	/forwarders/post/	Create or update webhook configuration
POST	/forwarders/post/reset-secret-key/	Rotate secret key used for signing outgoing requests
POST	/forwarders/post/test/	Send a sample payload to verify connectivity
GET	/forwarders/mongodb/	Retrieve MongoDB sink configuration
PUT	/forwarders/mongodb/	Create or update MongoDB sink configuration
POST	/forwarders/mongodb/test-connection/	Validate MongoDB URI/credentials

PostData Webhook

Retrieve Configuration

GET /api/v2/forwarders/post/
Authorization: Bearer <token>

Returns the organization’s webhook settings (URL, headers, secret key, status flags).

Update Configuration

PUT /api/v2/forwarders/post/
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://webhook.example.com/yanji",
  "header_template": {"Authorization": "Bearer {{secret_key}}"},
  "enabled": true
}

• secret_key can be supplied manually or rotated later.
• Updates create the configuration if none exists.

Reset Secret Key

POST /api/v2/forwarders/post/reset-secret-key/
Authorization: Bearer <token>

Generates a new 32-character alphanumeric secret and returns the refreshed configuration. Use this when rotating credentials on the receiving system.

Test Webhook

POST /api/v2/forwarders/post/test/
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://webhook.example.com/test",
  "secret_key": "custom-secret"
}

• If url or secret_key is omitted, the stored configuration is used.
• Sends a sample payload containing value, t, the_type, and agri_id to verify the endpoint and secret handling.
• Returns { "success": true } when HTTP 200 is received from the remote server; otherwise returns { "success": false, "message": ... } with HTTP 400.

MongoDB Forwarder

Retrieve Configuration

GET /api/v2/forwarders/mongodb/
Authorization: Bearer <token>

The response includes connection URI, database, collection, and synchronization options.

Update Configuration

PUT /api/v2/forwarders/mongodb/
Authorization: Bearer <token>
Content-Type: application/json

{
  "uri": "mongodb+srv://user:pwd@cluster.mongodb.net",
  "database": "yanji_data",
  "collection": "factors",
  "enabled": true
}

The serializer persists the configuration and ensures the organization association is set.

Test Connection

POST /api/v2/forwarders/mongodb/test-connection/
Authorization: Bearer <token>
Content-Type: application/json

{
  "uri": "mongodb://localhost:27017",
  "database": "yanji"
}

Attempts to connect using the supplied URI and reports whether the handshake succeeded.

Operational Notes

1. Singletons: Both forwarders use get_or_create with organization, so repeated GET/PUT calls are idempotent.
2. Security: Treat webhook secrets and MongoDB credentials like passwords. Store them securely and rotate periodically.
3. Error Logging: Failures during test endpoints are logged for diagnostics; check server logs if tests fail silently.
4. Throttling: Webhook deliveries inherit the system’s outbound queue capacity. Ensure your endpoint can handle bursts.
5. Data Shape: Forwarders send the same enriched payload format used by /devices/{device_pk}/data/ POST responses (agri_id, value, t, the_type, project_id, org_id). Use the Field Reference for exact field names.