Webhooks

Payload Structure

All webhook payloads follow the same structure:

{
  "id": "evt_1234567890",
  "type": "device.updated",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "id": "device_abc123",
    "name": "Farm Sensor 01",
    "status": "active",
    // ... event-specific data
  },
  "metadata": {
    "user_id": "user_123",
    "farm_id": "farm_456"
  }
}

Signature Verification

Always verify the webhook signature to ensure the request came from Precifarm:

// Node.js example
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

// Usage
app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-precifarm-signature'];
  const isValid = verifySignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook...
  res.status(200).send('OK');
});

Retry Policy

Best Practices