Webhook reference

Overview

PRIZM Cloud provides a webhook integration to send real-time IoT device data to your API server. This allows you to receive and process device updates as they occur.

This page is the contract for the receiving end. To create a webhook, see Data & Integrations.

How It Works

• PRIZM Cloud sends a POST request to the URL you specify.
• The request includes headers and a JSON payload with device data.
• Your server should be configured to handle these incoming requests.

Request Format

HTTP Method

POST

Headers

The request will include standard headers. You may expect additional authentication headers if configured.

Payload Example

[
  {
    "time": "1970-01-01T00:00:00Z",
    "companyId": "uuid",
    "deviceId": "uuid",
    "value": {
      "temperature": 22.5,
      "humidity": 60
    }
  }
]

Payload Fields

Configuring Your Webhook

Webhooks are created and managed on Settings → Data & Integrations — see Webhooks for the form. You give each one a name, the URL to call, and any custom headers your endpoint needs, and a Test Webhook button fires a real request before you save. A company can have three webhooks at a time.

Before you create one, make sure your server is:

• Accepting POST requests.
• Handling incoming JSON payloads.
• Responding with a 200 OK status on successful receipt.

Handling Requests

Your server should:

1. Validate the request (e.g., check for authentication if required).
2. Parse the JSON payload to extract device data.
3. Process the data according to your business logic.
4. Respond with a success status (200 OK) to acknowledge receipt.

Example Response:

{
  "status": "success",
  "message": "Data received"
}

Error Handling

If your server cannot process the request, respond with an appropriate HTTP status code (400, 500, etc.) and an error message. PRIZM Cloud may retry failed deliveries depending on the configuration.

Example Error Response:

{
  "status": "error",
  "message": "Invalid data format"
}

Security Considerations

• Use HTTPS for webhook URLs.
• Implement authentication (e.g., API keys, HMAC signatures) if needed.
• Validate and sanitize incoming data to prevent injection attacks.
• Use custom header key-value pairs for additional security validation.

For further assistance, contact PRIZM Cloud support.