Skip to main content
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.
1

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.
2

Obtain your credentials

  1. Log into your Flowent admin panel
  2. Navigate to Gateway Management
  3. Create an API Token (keep this secure)
  4. Create an HMAC Key (store this on your server)
These credentials are required for all API calls and webhook validation.
3

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.
4

Register your action

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:
  1. Use your local IP address in the webhook URL (e.g., http://192.168.1.100:8000/actions)
  2. 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

  1. Verify your webhook URL is accessible from the Flowent instance
  2. Check that your endpoint returns a 2xx status code for test requests
  3. Verify your server logs are showing incoming requests
  4. Ensure the action is properly registered (check admin panel)
  1. Most common issue: Make sure you’re calculating HMAC on the payload WITHOUT the signature field
  2. Verify you’re using the correct HMAC key from the admin panel
  3. Check that your JSON serialization matches Flowent’s format
  4. Use logging to compare your calculated vs received signature
  5. See the Signature Validation guide for detailed examples
Exchange your API token again to get a fresh JWT token. Tokens expire after 24 hours.

​
Next Steps