FlowMQ

Appearance

Webhooks ​

FlowMQ supports webhooks to integrate with external applications and services. Webhooks allow you to receive real-time notifications when messages are published to specific topics, enabling seamless integration with your existing systems and workflows.

Overview ​

Webhooks in FlowMQ provide:

  • Real-time Notifications: Instant delivery of message events
  • HTTP/HTTPS Support: Standard web protocols for integration
  • Custom Headers: Flexible authentication and metadata
  • Retry Logic: Automatic retry for failed deliveries
  • Security: TLS encryption and authentication options

Webhook Configuration ​

Basic Webhook Setup ​

json
{
  "name": "order-notifications",
  "topic_filter": "orders/#",
  "url": "https://your-app.com/webhooks/orders",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-webhook-secret",
    "Content-Type": "application/json",
    "X-FlowMQ-Source": "orders"
  },
  "timeout": 30,
  "retry_count": 3,
  "retry_delay": 5
}

Advanced Configuration ​

json
{
  "name": "critical-alerts",
  "topic_filter": "alerts/critical/#",
  "url": "https://your-monitoring.com/webhooks/alerts",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer your-secret",
    "Content-Type": "application/json",
    "X-Priority": "high"
  },
  "body_template": {
    "alert_type": "{{.topic}}",
    "message": "{{.payload}}",
    "timestamp": "{{.timestamp}}",
    "source": "flowmq"
  },
  "timeout": 10,
  "retry_count": 5,
  "retry_delay": 2,
  "max_retry_delay": 60,
  "enabled": true
}

Message Format ​

Default Webhook Payload ​

json
{
  "topic": "orders/eu/new",
  "payload": "{\"order_id\": \"12345\", \"amount\": 99.99}",
  "timestamp": "2024-01-15T10:30:00Z",
  "message_id": "msg_abc123",
  "properties": {
    "user_id": "12345",
    "priority": "high"
  }
}

Custom Body Template ​

json
{
  "webhook": {
    "body_template": {
      "event_type": "{{.topic}}",
      "data": "{{.payload}}",
      "received_at": "{{.timestamp}}",
      "message_id": "{{.message_id}}",
      "metadata": "{{.properties}}"
    }
  }
}

Integration Examples ​

E-commerce Order Processing ​

json
{
  "name": "order-webhook",
  "topic_filter": "orders/#",
  "url": "https://your-erp.com/api/orders",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer erp-api-key",
    "Content-Type": "application/json"
  },
  "body_template": {
    "order": "{{.payload}}",
    "source": "flowmq",
    "timestamp": "{{.timestamp}}"
  }
}

IoT Sensor Data ​

json
{
  "name": "sensor-webhook",
  "topic_filter": "sensors/+/temperature",
  "url": "https://your-analytics.com/webhooks/sensors",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer analytics-key",
    "Content-Type": "application/json"
  },
  "body_template": {
    "sensor_data": "{{.payload}}",
    "sensor_id": "{{.topic}}",
    "timestamp": "{{.timestamp}}"
  }
}

Slack Notifications ​

json
{
  "name": "slack-alerts",
  "topic_filter": "alerts/#",
  "url": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body_template": {
    "text": "Alert: {{.payload}}",
    "channel": "#alerts",
    "username": "FlowMQ Bot"
  }
}

Security ​

Authentication ​

json
{
  "webhook": {
    "headers": {
      "Authorization": "Bearer your-secret-token",
      "X-API-Key": "your-api-key",
      "X-Signature": "{{.signature}}"
    }
  }
}

TLS/SSL Configuration ​

json
{
  "webhook": {
    "url": "https://your-app.com/webhooks",
    "tls": {
      "verify_ssl": true,
      "ca_cert": "/path/to/ca-cert.pem",
      "client_cert": "/path/to/client-cert.pem",
      "client_key": "/path/to/client-key.pem"
    }
  }
}

Error Handling ​

Retry Configuration ​

json
{
  "webhook": {
    "retry_count": 3,
    "retry_delay": 5,
    "max_retry_delay": 60,
    "backoff_multiplier": 2,
    "timeout": 30
  }
}

Dead Letter Queue ​

json
{
  "webhook": {
    "dead_letter_topic": "webhooks/failed",
    "max_retries": 3,
    "on_failure": "send_to_dlq"
  }
}

Monitoring ​

Webhook Status ​

bash
# Check webhook status
curl -X GET "https://your-namespace.flowmq.io/api/v1/webhooks/order-notifications/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Format ​

json
{
  "success": true,
  "data": {
    "name": "order-notifications",
    "status": "active",
    "last_delivery": "2024-01-15T10:30:00Z",
    "success_count": 1250,
    "failure_count": 3,
    "last_error": null,
    "next_retry": null
  }
}

Best Practices ​

1. Use Appropriate Timeouts ​

json
{
  "webhook": {
    "timeout": 30,  // 30 seconds for most applications
    "retry_count": 3,
    "retry_delay": 5
  }
}

2. Implement Idempotency ​

json
{
  "webhook": {
    "headers": {
      "X-Message-ID": "{{.message_id}}",
      "X-Timestamp": "{{.timestamp}}"
    }
  }
}

3. Handle Large Payloads ​

json
{
  "webhook": {
    "max_payload_size": 1048576,  // 1MB
    "compression": "gzip",
    "headers": {
      "Content-Encoding": "gzip"
    }
  }
}

4. Use Topic Filtering ​

json
{
  "webhook": {
    "topic_filter": "orders/eu/#",  // Only EU orders
    "url": "https://eu-app.com/webhooks"
  }
}

Integration Patterns ​

Multiple Webhooks for Different Events ​

json
[
  {
    "name": "order-created",
    "topic_filter": "orders/+/created",
    "url": "https://erp.com/webhooks/orders/created"
  },
  {
    "name": "order-cancelled",
    "topic_filter": "orders/+/cancelled",
    "url": "https://erp.com/webhooks/orders/cancelled"
  },
  {
    "name": "order-shipped",
    "topic_filter": "orders/+/shipped",
    "url": "https://logistics.com/webhooks/shipping"
  }
]

Conditional Webhooks ​

json
{
  "name": "high-value-orders",
  "topic_filter": "orders/#",
  "url": "https://finance.com/webhooks/high-value",
  "condition": {
    "field": "amount",
    "operator": ">",
    "value": 1000
  }
}

Webhook Chaining ​

json
{
  "name": "order-processing",
  "topic_filter": "orders/#",
  "url": "https://processor.com/webhooks",
  "on_success": {
    "topic": "orders/processed",
    "payload": "{{.response}}"
  },
  "on_failure": {
    "topic": "orders/failed",
    "payload": "{{.error}}"
  }
}

Testing Webhooks ​

Test Webhook Endpoint ​

bash
# Test webhook delivery
curl -X POST "https://your-namespace.flowmq.io/api/v1/webhooks/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-webhook",
    "url": "https://webhook.site/your-unique-url",
    "topic_filter": "test/#",
    "method": "POST"
  }'

Webhook Testing Tools ​

  • webhook.site: Receive and inspect webhooks
  • ngrok: Expose local servers for testing
  • Postman: Test webhook endpoints
  • cURL: Command-line testing

Troubleshooting ​

Common Issues ​

  1. Timeout Errors

    json
    {
  "webhook": {
    "timeout": 60,  // Increase timeout
    "retry_count": 5
  }
}

  2. Authentication Errors

    json
    {
  "webhook": {
    "headers": {
      "Authorization": "Bearer valid-token"
    }
  }
}

  3. SSL Certificate Issues

    json
    {
  "webhook": {
    "tls": {
      "verify_ssl": false  // For testing only
    }
  }
}

Debug Mode ​

json
{
  "webhook": {
    "debug": true,
    "log_requests": true,
    "log_responses": true
  }
}

Next Steps ​

Future Enhancements ​

Webhook capabilities in FlowMQ will continue to evolve with:

  • Advanced Filtering: Complex message filtering rules
  • Rate Limiting: Configurable delivery rates
  • Batch Processing: Group multiple messages
  • Webhook Templates: Pre-built configurations
  • Enhanced Monitoring: Real-time webhook analytics
  • Webhook Marketplace: Community-contributed integrations

© 2025 FlowMQ. All rights reserved.