Security and Authentication

1. Navigate to the Webhook Configuration section in your dashboard.

2. Click on View Secret Key (masked by default).

3. Securely store this key on your server.

HMAC Signature Generation

We use HMAC with SHA256 to sign each request.

• Signature Algorithm: HMAC-SHA256

• String to Sign: The JSON payload as a string

• Secret Key: Your shared secret key

Verifying the Signature

To verify incoming requests:

1. Extract the signature from the X-Weguard-Signature header.

2. Compute the HMAC signature using the payload and your shared secret key.

3. Compare the computed signature with the received signature:

• If they match, the request is authentic.

• If not, reject the request.
  

1. Additionally, we include a header, X-Webhook-Source: weguard, in our requests, which you can use to verify that the request originated from us.

Client-Side HMAC Signature Verification Example (Go)

Here’s an example of verifying the signature in Go:

package main

import (

   "crypto/hmac"

   "crypto/sha256"

   "encoding/hex"

   "io/ioutil"

   "net/http"

)

func verify(w http.ResponseWriter, r *http.Request) {

   key := []byte("your-shared-secret-key")

   sig := r.Header.Get("X-Weguard-Signature")

   body, _ := ioutil.ReadAll(r.Body)

   mac := hmac.New(sha256.New, key)

   mac.Write(body)

   expectedSig := hex.EncodeToString(mac.Sum(nil))

   if hmac.Equal([]byte(sig), []byte(expectedSig)) {

       // Signature is valid

       w.WriteHeader(http.StatusOK)

   } else {

       // Signature is invalid

       w.WriteHeader(http.StatusUnauthorized)

   }

}

func main() {

   http.HandleFunc("/", verify)

   http.ListenAndServe(":8080", nil)

}

Custom Headers

Each webhook request includes the following custom headers:

• X-Webhook-Source: Weguard

• X-Weguard-Signature: The HMAC signature for verification.
  

Retry Mechanism

To ensure reliable data delivery, the webhook employs a retry mechanism:

• Automatic Retries: If the endpoint is unreachable or returns an error, retries will be attempted.

• Retry Limit: Up to 3 retries.

• Exponential Backoff: Delays between retries increase to avoid overwhelming your server.

• Failure Handling: After exhausting retries, data will be moved to a dead-letter queue and eventually discarded.

Rate Limiting Considerations

The frequency of location updates depends on:

• The number of devices in your account.

• The update frequency of each device.

Ensure your server can handle the potential load. Consider implementing queueing or throttling mechanisms to manage bursts of data efficiently.