Development Setup

Prerequisites:

A server or local environment to host your webhook endpoints
A Flowent instance with API Gateway enabled
Admin access to your Flowent instance

Follow these steps to set up your development environment for building with the Flowent API Gateway.

Set up your development server

Create a simple webhook server to receive requests from Flowent. Here are the requirements:

Accept POST requests with JSON payloads
Validate HMAC signatures using your HMAC key
Return responses in the expected format: { "result": "...", "error": "" }
Handle test validation requests during action registration

Refer to the API Concepts guide for detailed implementation patterns.

Obtain your credentials

Log into your Flowent admin panel
Navigate to Gateway Management
Create an API Token (keep this secure)
Create an HMAC Key (store this on your server)

These credentials are required for all API calls and webhook validation.

Test your webhook endpoint

Ensure your webhook endpoint is accessible from the Flowent instance:

# Test that your server responds to POST requests
curl -X POST https://your-server.com/actions/test \
  -H "Content-Type: application/json" \
  -d '{"action_name": "test", "parameters": {}, "timestamp": 123456}'

Your server should return a 2xx status code.

Use the Flowent API to register your action:

# Exchange API token for JWT
JWT=$(curl -X POST https://your-flowent-instance.com/api/v1/gateway/token/exchange \
  -H "Content-Type: application/json" \
  -d '{"api_token": "your-api-token"}' \
  | jq -r '.jwt_token')

# Register your action
curl -X POST https://your-flowent-instance.com/api/v1/gateway/actions \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_action",
    "description": "My custom action",
    "webhook_url": "https://your-server.com/actions/my_action",
    "json_schema": {
      "type": "object",
      "properties": {
        "param1": {"type": "string"}
      },
      "required": ["param1"]
    }
  }'

Local Development Best Practices

Environment Variables

Store sensitive credentials in environment variables, never hardcode them:

# .env
FLOWENT_API_TOKEN=your_api_token
FLOWENT_HMAC_KEY=your_hmac_key
FLOWENT_BASE_URL=https://your-flowent-instance.com

Logging

Log all webhook requests for debugging:

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def handle_webhook(request_data):
    logger.info(f"Received webhook: {request_data}")
    logger.info(f"Action: {request_data.get('action_name')}")
    logger.info(f"Parameters: {request_data.get('parameters')}")

Testing

Always test your webhook handler with test requests:

curl -X POST https://your-server.com/actions/my_action \
  -H "Content-Type: application/json" \
  -d '{
    "action_name": "my_action",
    "parameters": {},
    "timestamp": '$(date +%s)',
    "test": true
  }'

Exposing Local Server to Flowent

If you’re running Flowent and your development server on the same network:

Use your local IP address in the webhook URL (e.g., http://192.168.1.100:8000/actions)
Use tunneling tools like ngrok to expose your local server:

# Install ngrok
brew install ngrok  # or download from ngrok.com

# Expose your local server
ngrok http 8000

# Use the provided URL in your webhook registration
# https://xxxx-xx-xxx-xx-x.ngrok.io/actions/my_action

Troubleshooting

Webhook not receiving calls

Verify your webhook URL is accessible from the Flowent instance
Check that your endpoint returns a 2xx status code for test requests
Verify your server logs are showing incoming requests
Ensure the action is properly registered (check admin panel)

HMAC signature validation failing

Most common issue: Make sure you’re calculating HMAC on the payload WITHOUT the signature field
Verify you’re using the correct HMAC key from the admin panel
Check that your JSON serialization matches Flowent’s format
Use logging to compare your calculated vs received signature
See the Signature Validation guide for detailed examples

JWT token expired

Exchange your API token again to get a fresh JWT token. Tokens expire after 24 hours.

Next Steps

Review the API Concepts for detailed technical information
Explore the API Reference for all available endpoints

Getting Started

Guides

API Reference

Local Development Best Practices

Environment Variables

Logging

Testing

Exposing Local Server to Flowent

Troubleshooting

Next Steps

​Local Development Best Practices

​Environment Variables

​Logging

​Testing

​Exposing Local Server to Flowent

​Troubleshooting

​Next Steps

Local Development Best Practices

Environment Variables

Logging

Testing

Exposing Local Server to Flowent

Troubleshooting

Next Steps