Webhooks

Webhooks allow you to receive real-time notifications when important events occur in your IMMUNE system. Instead of constantly polling the API, webhooks push updates directly to your server, making them ideal for responding quickly to predictions and alerts.

Registering webhooks

You can register webhook endpoints through the IMMUNE dashboard or via the API:

curl -X POST https://api.immune.dev/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -d url="https://your-domain.com/webhooks" \
  -d "events[]"="prediction.created" \
  -d "events[]"="alert.triggered"

Available events

Name
prediction.created
Description
Triggered when a new prediction is generated for any of your monitored equipment.
Name
alert.triggered
Description
Triggered when sensor readings exceed defined thresholds or anomalies are detected.
Name
sensor.status_changed
Description
Triggered when a sensor's status changes (online/offline/error).
Name
maintenance.scheduled
Description
Triggered when preventive maintenance is automatically scheduled.

Webhook payloads

Here's an example of a prediction webhook payload:

{
  "id": "evt_123",
  "type": "prediction.created",
  "created_at": "2024-01-20T15:30:00Z",
  "data": {
    "prediction_id": "pred_abc123",
    "equipment_id": "pump_001",
    "confidence": 0.95,
    "predicted_failure_time": "2024-02-01T00:00:00Z",
    "recommended_action": "Replace bearing",
    "supporting_data": {
      "vibration_trend": "increasing",
      "temperature_anomalies": true
    }
  }
}

Securing webhooks

To ensure webhook requests are coming from IMMUNE, we sign each request with a secret key. You should verify this signature before processing the webhook:

import crypto from 'crypto'

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

// In your webhook handler
app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-immune-signature']
  const isValid = verifyWebhookSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  )

  if (isValid) {
    // Process the webhook
    handlePrediction(req.body)
    res.sendStatus(200)
  } else {
    // Request could not be verified
    res.sendStatus(401)
  }
})

Best practices

Always verify webhook signatures
Respond quickly (within 5 seconds) to webhook requests
Implement retry logic for failed webhook deliveries
Store your webhook secret securely
Set up monitoring for webhook processing
Handle duplicate events (use the event ID for deduplication)

Testing webhooks

Use our webhook testing tool in the dashboard to simulate events and verify your integration:

curl -X POST https://api.immune.dev/v1/webhooks/test \
  -H "Authorization: Bearer {token}" \
  -d "event_type"="prediction.created"

This will send a test event to all your registered webhook endpoints.