> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowent.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Setup

> Set up your local development environment for building webhook endpoints with Flowent API Gateway. Configure your server, credentials, and testing tools.

<Info>
  **Prerequisites**:

  * A server or local environment to host your webhook endpoints
  * A Flowent instance with API Gateway enabled
  * Admin access to your Flowent instance
</Info>

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

<Steps>
  <Step title="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](/api-concepts) guide for detailed implementation patterns.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Test your webhook endpoint">
    Ensure your webhook endpoint is accessible from the Flowent instance:

    ```bash theme={null}
    # 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.
  </Step>

  <Step title="Register your action">
    Use the Flowent API to register your action:

    ```bash theme={null}
    # 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"]
        }
      }'
    ```
  </Step>
</Steps>

## Local Development Best Practices

### Environment Variables

Store sensitive credentials in environment variables, never hardcode them:

```bash theme={null}
# .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:

```python theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Webhook not receiving calls">
    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)
  </Accordion>

  <Accordion title="HMAC signature validation failing">
    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](/api-concepts#signature-validation) guide for detailed examples
  </Accordion>

  <Accordion title="JWT token expired">
    Exchange your API token again to get a fresh JWT token. Tokens expire after 24 hours.
  </Accordion>
</AccordionGroup>

## Next Steps

* Review the [API Concepts](/api-concepts) for detailed technical information
* Explore the [API Reference](/api-reference/introduction) for all available endpoints