Skip to main content

​
Custom Webhooks

Send alert data to any HTTP endpoint. Perfect for custom integrations, internal tools, or services not directly supported by Roboticks.

​
Features

  • Configurable HTTP method (POST, PUT, etc.)
  • Custom headers for authentication
  • JSON payload with full alert details
  • Webhook signature for security (HMAC-SHA256)
  • Automatic retry on failure

​
Setup

​
Step 1: Set Up Your Endpoint

Create an HTTP endpoint on your server that can receive POST requests with JSON payloads: 
# Example Flask endpoint
from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "your-signing-secret"

@app.route('/roboticks-webhook', methods=['POST'])
def handle_webhook():
    # Verify signature
    signature = request.headers.get('X-Roboticks-Signature')
    payload = request.get_data()

    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, f"sha256={expected}"):
        return "Invalid signature", 401

    # Process the alert
    data = request.json
    print(f"Alert: {data['alert']['name']} - {data['device']['name']}")

    return "OK", 200

​
Step 2: Configure in Roboticks

  1. Go to Settings > Integrations in Roboticks
  2. Find Custom Webhook and click Add
  3. Enter your webhook URL
  4. Optionally add a signing secret for verification
  5. Click Create

​
Step 3: Test the Integration

Use the Test button to send a sample payload and verify your endpoint is working correctly.

​
Configuration Options

OptionDescriptionRequired
Webhook URLYour endpoint URL (HTTPS recommended)Yes
HTTP MethodPOST, PUT, PATCHNo (default: POST)
Signing SecretSecret for HMAC signature verificationNo
NameDisplay name for this integrationYes
EnabledToggle the integration on/off-

​
Payload Format

Webhooks receive JSON payloads with the following structure: 
{
  "event_type": "alert.triggered",
  "timestamp": "2025-01-10T10:23:45Z",
  "alert": {
    "id": 123,
    "name": "Device Offline",
    "severity": "critical",
    "status": "active",
    "message": "Device has not sent a heartbeat in 5 minutes",
    "rule_id": 456,
    "triggered_at": "2025-01-10T10:23:45Z"
  },
  "device": {
    "id": 789,
    "name": "warehouse-robot-01",
    "type": "robot",
    "status": "offline"
  },
  "project": {
    "id": 10,
    "name": "Warehouse Operations",
    "slug": "warehouse"
  },
  "organization": {
    "id": 1,
    "name": "Acme Corp",
    "slug": "acme"
  },
  "links": {
    "alert": "https://app.roboticks.io/alerts/123",
    "device": "https://app.roboticks.io/devices/789"
  }
}

​
Event Types

Event TypeDescription
alert.triggeredAlert condition met
alert.resolvedAlert condition cleared
alert.acknowledgedAlert acknowledged by user

​
Signature Verification

If you provide a signing secret, all webhooks include an X-Roboticks-Signature header: 
X-Roboticks-Signature: sha256=abc123...

​
Verification Steps

  1. Get the raw request body (before JSON parsing)
  2. Compute HMAC-SHA256 using your signing secret
  3. Compare with the X-Roboticks-Signature header value
import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, f"sha256={expected}")
Always verify webhook signatures in production to prevent unauthorized requests.

​
Retry Behavior

Failed webhook deliveries are automatically retried:
AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
Final retry2 hours
After 5 failed attempts, the webhook is marked as failed and logged.

​
Troubleshooting

  • Verify the URL is correct and publicly accessible
  • Check that HTTPS certificate is valid (if using HTTPS)
  • Ensure your firewall allows incoming requests
  • Review integration logs for error messages
  • Ensure you’re using the raw request body (not parsed JSON)
  • Verify the signing secret matches exactly
  • Check for any proxy modifications to the payload
  • Webhook endpoints should respond within 30 seconds
  • Process webhooks asynchronously if needed
  • Return 200 OK immediately, process data in background
Default is POST. If your endpoint requires PUT or PATCH, configure the HTTP Method option.

​
Best Practices

  1. Always verify signatures - Protect against unauthorized webhook calls
  2. Respond quickly - Return 200 OK within 30 seconds
  3. Handle duplicates - Use alert.id for idempotency
  4. Use HTTPS - Encrypt webhook data in transit
  5. Log incoming webhooks - Helpful for debugging integration issues