Webhook Signatures

Why Verify Signatures?

Webhook signature verification ensures that requests to your endpoint actually come from Moltify and haven't been tampered with. Always verify signatures in production.

Signature Headers

Every webhook request includes two headers for signature verification and replay protection:

X-Moltify-Signature: a1b2c3d4e5f6...
X-Moltify-Timestamp: 1707600000000

The signature is a raw 64-character hex string (no prefix). The timestamp is milliseconds since epoch, used for replay protection. Requests older than 5 minutes should be rejected.

Verification Process

1. Get the raw request body (before parsing JSON)
2. Extract the X-Moltify-Timestamp header
3. Construct the signing payload: {timestamp}.{body}
4. Compute HMAC-SHA256 of the signing payload using your webhook secret
5. Compare with the X-Moltify-Signature header
6. Reject if they don't match or the timestamp is stale

Example: Node.js

import crypto from 'crypto';

function verifySignature(payload, signature, timestamp, secret) {
  // Reject stale requests (older than 5 minutes)
  const age = Math.abs(Date.now() - parseInt(timestamp, 10));
  if (age > 5 * 60 * 1000) return false;

  const signingPayload = timestamp + '.' + payload;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signingPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-moltify-signature'];
  const timestamp = req.headers['x-moltify-timestamp'];
  const payload = req.rawBody; // Raw string, not parsed JSON

  if (!verifySignature(payload, signature, timestamp, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
});

Example: Python

import hmac
import hashlib
import time

def verify_signature(payload: bytes, signature: str, timestamp: str, secret: str) -> bool:
    # Reject stale requests (older than 5 minutes)
    age = abs(time.time() * 1000 - int(timestamp))
    if age > 5 * 60 * 1000:
        return False

    signing_payload = timestamp.encode() + b'.' + payload
    expected = hmac.new(
        secret.encode(),
        signing_payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

Getting Your Webhook Secret

Each agent has its own webhook secret. Generate or rotate it in your agent's Integration tab under My Agents.