Webhook Security

Each webhook request sent carries its own signature in the header. A public key obtained from the portal or our support team can be used to validate the signature and ensure the authenticity of the request.

Your server must accept POST requests — all webhook notifications are sent via POST.

Setting Up Your Webhook URL

igloohome API Partners

Add your webhook URL on the igloohome API portal, in the Webhooks section.

iglooconnect Partners

Email dev+support@igloocompany.co to get your webhook URL set up — we'll add it right away. An iglooconnect portal for self-service webhook URL management is planned.

Signature Process

Part of the webhook request is passed through HMAC, where the resulting digest is signed using our RSA private key.

Webhook Request Validation

Given the following HTTPS request:

POST /example/path HTTP/1.1
Host: example-host.com
Date: Sat, 20 Jun 2015 12:34:56 GMT
Accept: application/json
Content-Type: application/json
Content-Length: 29
x-igloocompany-sha256: "QA...=="

{ "payload": "example payload" }

The webhook request signature is carried in the x-igloocompany-sha256 header, base64-encoded.

Signed Data Construction

Construct the signed data from the following fields, extracted from the request, in order:

• Method (all uppercase)
• Host
• URL Path
• Content Type
• Date
• Body

Concatenate each item, delimited by the bar (|) character. For the request above, the final concatenated payload is:

POST|example-host.com|/example/path|application/json|Sat, 20 Jun 2015 12:34:56 GMT|{"payload":"example"}

HMAC Process

Hash the constructed signed data using HMAC with the SHA-256 hashing algorithm to get the HMAC digest.

Signature Validation

Validate the HMAC digest against the signature extracted from the header and decoded, using SHA-256.

Public Key

Contact dev+support@igloocompany.co to request the public key. The key you receive is base64-encoded.

Working Example

The following Node.js example (crypto library, v16.x LTS) validates the signature of an example payload with a sample public key:

// Using nodejs crypto library.
import * as crypto from 'crypto';

// The example payload that we'll be validating.
const payload = 'POST|example-host.com|/example/path|application/json|Sat, 20 Jun 2015 12:34:56 GMT|{"payload":"example payload"}';

// We use SHA-256 hash algorithm in both the HMAC computation and signature validation.
const hashAlgorithm = 'sha256';

// Decode both the public key string and signature string.
// (Assuming `publicKeyString` and `signatureString` are both valid.)
const publicKey = Buffer.from(publicKeyString, 'base64');
const signature = Buffer.from(signatureString, 'base64');

// Compute the hash using HMAC.
const hmacDigest = crypto.createHmac(hashAlgorithm, publicKey)
  .update(payload, 'ascii')
  .digest();

// Validate signature.
const result = crypto.verify(
  hashAlgorithm,
  hmacDigest,
  crypto.createPublicKey({
      key: publicKey,
      format: 'der',
      type: 'pkcs1'
  }),
  signature
);

// Output validation result.
console.log('signature valid:', result); // signature valid: true