Managing webhook Destinations

• Creating Destinations: Use POST /destination to register a new webhook Destination. See Create a new Destination.
• Listing Destinations: Use GET /destination to view all your webhook Destinations. See Get all Destinations.
• Updating Destinations: Use PATCH /destination/:id to modify a Destination. See Update an existing Destination.
• Deleting Destinations: Use DELETE /destination/:id to remove a specific webhook Destination. See Delete a Destination.

Receiving messages

Triggering message forwarding

• Send a device message from a device to initiate message forwarding.
• Await messages at your registered webhook Destination shortly after sending the device message.
• Messages arrive in batches to your configured webhook Destination.
• Messages from MQTT topics prefixed with $ENV/$TEAM_ID/m are forwarded, with the exception of messages sent to $ENV/$TEAM_ID/m/d/$DEVICE_ID/d2c/bin.

Security and SSL verification

• Verifying requests: Use the x-nrfcloud-signature header to verify incoming requests. This signature is an HMAC hex digest of the request payload, hashed using your provided secret. Employ constant-time string comparisons to mitigate timing attacks.
• SSL verification: SSL verification is standard for payload delivery unless you disable it using the verifySsl property in your webhook configuration.

Handling errors

• Non-2xx responses from your Destination webhook are logged as errors. Access the errors property of the Destination to review the five most recent errors within the past 30 days.

Access control

• Full Destination management is limited to Admin and Owner roles. Destination viewing is allowed for Editor and Viewer roles.

Below is an example of a simple Node.js server that receives webhook requests, verifies the x-nrfcloud-signature header, and responds with a status code of 200 along with the x-nrfcloud-team-id header. This example uses Express, a popular web framework for Node.js, and the crypto module for signature verification.

const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');

const app = express();
const port = 3000;

// Replace this with your actual secret key
const secretKey = 'yourSecretKey';

app.use(bodyParser.json());

// Verify nRF Cloud signature
const verifySignature = (req) => {
    const signature = req.headers['x-nrfcloud-signature'];
    const body = JSON.stringify(req.body);

    // Create HMAC hex digest
    const hmac = crypto.createHmac('sha256', secretKey);
    hmac.update(body, 'utf8');
    const digest = hmac.digest('hex');

    return digest === signature;
};

app.post('/webhook', (req, res) => {
    if (verifySignature(req)) {
        // Your logic here - process the request
        
        // Respond with 200 OK and x-nrfcloud-team-id header
        res.set('x-nrfcloud-team-id', 'yourTeamId');
        res.status(200).send('Webhook received successfully.');
    } else {
        res.status(401).send('Invalid signature.');
    }
});

app.listen(port, () => {
    console.log(`Webhook receiver running on port ${port}`);
});