HTTP Request Block

“HTTP Request” Block

What is an “HTTP Request” Block

The “HTTP Request” Block is a powerful integration element in Grailgun that allows your bot to communicate with external APIs and web services. This Block enables you to fetch data, send information, trigger webhooks, and integrate with third-party platforms, making your bot capable of accessing virtually any web-based service.

Main Functions

• Calling external REST APIs
• Fetching data from web services
• Sending data to external platforms
• Integrating with payment processors
• Validating user information via third-party services
• Triggering webhooks and automation workflows
• Retrieving real-time information (weather, news, prices, etc.)

Creation and Configuration

How to Add an “HTTP Request” Block

1. Open the bot builder
2. From the Blocks panel, select “Add HTTP Request”
3. The Block will be added to the workspace

Configuring HTTP Request Parameters

1. Double-click on the “HTTP Request” Block in the builder
2. Set a descriptive name for the request
3. Enter the API endpoint URL
4. Select HTTP method (GET, POST, PUT, PATCH, DELETE)
5. Configure request body (for POST/PUT/PATCH)
6. Optionally expand Advanced Settings for headers, query parameters, timeout, and retries
7. Test the request to verify it works
8. Click “Save” to apply settings

Basic Configuration

Name

A descriptive title for this HTTP Request Block to help identify it in your flow.

Example: “Fetch User Profile”, “Send Payment Webhook”, “Validate Email”

URL

The complete endpoint URL for the API you want to call.

Requirements:

• Must be a valid URL format
• Typically starts with https:// (recommended) or http://
• Can include variables using {variable_name} syntax

Examples:

https://api.example.com/users/USER_ID
https://api.weather.com/v1/current?city=London
https://webhook.site/your-unique-id

Note: Replace USER_ID with {user_id} syntax when using variables.

URL Validation:

• The system validates URL format and shows errors for invalid URLs
• Warnings appear for potential issues (e.g., using http instead of https)

HTTP Method

Select the appropriate HTTP method for your request:

• GET - Retrieve data from the server (most common)
• POST - Send data to create new resources
• PUT - Update existing resources completely
• PATCH - Partially update existing resources
• DELETE - Remove resources

Request Body

For POST, PUT, and PATCH methods, you can send data in the request body.

Supported Formats:

• JSON (most common)
• Plain text
• Form data

Example JSON Body:

{
  "user_id": "USER_ID",
  "email": "USER_EMAIL",
  "subscription_type": "premium"
}

Variables in Body: Use {variable_name} syntax to include dynamic values from your flow variables (replace USER_ID with {user_id}, etc.).

Advanced Settings

Click “Advanced Settings” to access additional configuration options:

Headers

Custom HTTP headers to include with your request.

Common Headers:

• Content-Type: application/json - Specify JSON content
• Authorization: Bearer TOKEN - API authentication (use {api_token} for variables)
• User-Agent: GrailgunBot/1.0 - Identify your bot
• Accept: application/json - Specify expected response format

Adding Headers:

1. Click “Add Header” button
2. Enter header name (e.g., “Authorization”)
3. Enter header value (e.g., “Bearer YOUR_API_KEY”)
4. Variables supported: {variable_name}

Query Parameters

URL query parameters to append to the request URL.

Example:

• Parameter: api_key, Value: your_key_here
• Parameter: user_id, Value: your user ID variable
• Results in: https://api.example.com?api_key=your_key_here&user_id=123

Adding Parameters:

1. Click “Add Parameter” button
2. Enter parameter name
3. Enter parameter value
4. Variables supported: {variable_name}

Timeout (Seconds)

Maximum time to wait for a response before considering the request failed.

• Default: 30 seconds
• Range: 1-600 seconds (10 minutes)
• Recommendation: Use shorter timeouts (5-10 seconds) for user-facing flows

Retries

Number of times to retry the request if it fails.

• Default: 3 retries
• Range: 0-10 retries
• Recommendation: Use 1-3 retries for important requests, 0 for non-critical

Success Status Codes

HTTP status codes that indicate a successful response.

• Default: 200, 201, 202, 204
• Format: Comma-separated list (e.g., “200, 201, 204”)
• Common Success Codes:
  • 200 - OK (standard success)
  • 201 - Created (successful creation)
  • 202 - Accepted (request accepted for processing)
  • 204 - No Content (successful with no response body)

Testing Requests

Before deploying your flow, test the HTTP request:

1. Configure all request parameters
2. Click “Test Request” button
3. View the test result showing:
   • Success/Error status
   • HTTP status code and status text
   • Response data

Test Results Display:

• ✅ Green badge - Request succeeded
• ❌ Red badge - Request failed
• Full response body (JSON formatted or plain text)

Use testing to:

• Verify API credentials
• Check response format
• Validate variable substitution
• Debug connection issues

Connection Points

The HTTP Request Block has branching outputs:

• IN - Accepts connection from previous Blocks
• SUCCESS - Connected Block executes when request succeeds (status code in success list)
• ELSE - Connected Block executes when request fails (timeout, network error, or non-success status code)

This allows you to handle success and failure scenarios differently.

Usage Examples

Fetch Weather Data

Scenario: Get current weather for user’s city

Configuration:

• Method: GET
• URL: https://api.openweathermap.org/data/2.5/weather
• Query Parameters:
  • q: user_city variable
  • appid: YOUR_API_KEY
  • units: metric

Flow:

1. Message: “Which city?”
2. Variable Change: Set “user_city” = USER_RESPONSE
3. HTTP Request: Fetch weather
   • SUCCESS: Variable Change: Set “weather” = response data
   • SUCCESS: Message: “Temperature in [city]: [temp]°C”
   • ELSE: Message: “Couldn’t fetch weather data”

Validate Email Address

Scenario: Check if email exists using validation API

Configuration:

• Method: GET
• URL: https://api.email-validator.net/api/verify
• Query Parameters:
  • email: user_email variable
  • apiKey: YOUR_API_KEY

Flow:

1. Message: “Enter your email”
2. Variable Change: Set “user_email” = USER_RESPONSE
3. HTTP Request: Validate email
   • SUCCESS: Message: “Email verified!”
   • ELSE: Message: “Invalid email, try again”

Send Webhook Notification

Scenario: Notify external system of user action

Configuration:

• Method: POST
• URL: https://hooks.slack.com/services/YOUR/WEBHOOK/URL
• Body:

{
  "text": "User NAME completed registration",
  "username": "GrailgunBot"
}

Note: Replace NAME with {user_name} variable in your actual request.

Flow:

1. Variable Change: Set various registration data
2. HTTP Request: Send webhook
3. Continue with normal flow (success/failure both proceed)

Payment Verification

Scenario: Verify payment with payment processor

Configuration:

• Method: POST
• URL: https://api.stripe.com/v1/payment_intents/{payment_id}/confirm
• Headers:
  • Authorization: Bearer YOUR_STRIPE_SECRET_KEY
  • Content-Type: application/x-www-form-urlencoded

Flow:

1. HTTP Request: Confirm payment
   • SUCCESS:
     • Status Change: Set status to “Premium”
     • Message: “Payment successful! Welcome to Premium.”
   • ELSE:
     • Message: “Payment failed. Please try again.”

User Data Sync

Scenario: Sync user data with CRM

Configuration:

• Method: PUT
• URL: https://api.yourcrm.com/users/USER_ID (use {user_id} variable)
• Headers:
  • Authorization: Bearer YOUR_CRM_API_KEY
  • Content-Type: application/json
• Body:

{
  "email": "USER_EMAIL",
  "subscription_status": "STATUS",
  "last_active": "TIMESTAMP"
}

Note: Replace USER_EMAIL, STATUS, and TIMESTAMP with variable syntax like {user_email} in your actual request.

Flow:

1. HTTP Request: Update CRM
   • SUCCESS: Alert: “CRM updated for user ID”
   • ELSE: Alert: “CRM sync failed for user ID”

Fetch Dynamic Content

Scenario: Get personalized content from content API

Configuration:

• Method: GET
• URL: https://api.content-service.com/articles/recommended
• Query Parameters:
  • user_id: user_id variable
  • category: user_preference variable
  • limit: 5
• Headers:
  • Authorization: Bearer YOUR_API_KEY

Flow:

1. HTTP Request: Fetch articles
   • SUCCESS:
     • Message: “Here are articles for you: [titles]”
   • ELSE:
     • Message: “Couldn’t load articles right now”

Working with Response Data

Storing Response in Variables

HTTP Request responses can be stored in variables for later use:

1. After successful request, use Variable Change Block
2. Set variable to extract specific fields from response
3. Reference in subsequent messages or conditions

Note: Currently, automatic response parsing into variables may require additional configuration. Check your bot’s capabilities for response data handling.

Using Response Data in Messages

If your system supports it, reference response data in messages:

The API returned: {http_response.data.value}

Check documentation for your specific implementation’s response handling capabilities.

Security Best Practices

API Keys and Secrets

• Never hardcode sensitive keys in URLs or body if possible
• Store API keys in variables or bot configuration
• Use environment-specific keys (dev, production)
• Rotate keys regularly

HTTPS vs HTTP

• Always use HTTPS for production APIs
• HTTP is unencrypted and exposes data in transit
• The system warns you when using HTTP URLs

Authentication

Common Methods:

1. Bearer Token in Authorization header
2. API Key in header or query parameter
3. Basic Authentication (username:password)
4. OAuth tokens (obtain separately, use in requests)

Data Privacy

• Don’t send unnecessary user data to third parties
• Comply with GDPR and privacy regulations
• Inform users about data sharing in terms of service
• Minimize data in requests to what’s required

Error Handling

Common Errors and Solutions

URL Validation Error:

• Check URL format (include protocol https://)
• Ensure no typos in domain name
• Verify variables exist if using {variable_name}

Timeout:

• Increase timeout setting
• Check if API is responding slowly
• Consider if API is down

401 Unauthorized:

• Verify API key/token is correct
• Check if token has expired
• Ensure Authorization header is properly formatted

404 Not Found:

• Verify endpoint URL is correct
• Check if resource ID exists
• Ensure API version in URL is current

500 Server Error:

• API may be experiencing issues
• Check API status page
• Implement retry logic
• Use ELSE path to handle gracefully

Handling Failures in Flow

Always implement ELSE path for HTTP Request Blocks:

HTTP Request
  → SUCCESS: Continue normal flow
  → ELSE:
    → Message: "Service temporarily unavailable"
    → Alert: "API call failed for user ID"
    → (Optional) Retry or alternative action

Tips and Recommendations

• Test thoroughly: Always test requests before deploying
• Handle failures: Implement ELSE paths for all HTTP Requests
• Use timeouts: Set appropriate timeouts for user experience
• Retry wisely: Use retries for network issues, not for client errors (4xx)
• Log important calls: Use Alert Blocks to monitor critical API calls
• Variables everywhere: Use variables for dynamic data in URLs, headers, body, params
• Descriptive names: Name your HTTP Request Blocks clearly
• Security first: Use HTTPS, secure API keys, minimize data sharing
• Monitor responses: Check response formats match expectations
• Document integrations: Keep track of which APIs you’re using and why

Frequently Asked Questions

Can I make multiple API calls in sequence?

Yes! Chain multiple HTTP Request Blocks together, using SUCCESS/ELSE paths to control flow based on results.

How do I parse JSON responses?

Response parsing capabilities depend on your bot implementation. Check if automatic variable extraction from JSON responses is supported.

Can I upload files via HTTP Request?

This depends on your implementation. Standard HTTP Request Blocks typically support JSON/text data, not file uploads.

Are requests made in real-time?

Yes, HTTP Requests are made synchronously during flow execution. The flow waits (up to timeout) for the response before proceeding.

Can I use HTTP Request for webhooks?

Yes! Webhooks are typically POST requests to a specific URL. Configure method as POST and include required webhook payload.

What happens if the API is down?

The request will timeout or fail, triggering the ELSE path. Always implement error handling for this scenario.

Can I customize retry behavior?

You can set the number of retries (0-10) in Advanced Settings. Retry logic typically uses exponential backoff.

Are there rate limits?

Rate limits depend on the external API you’re calling. Check the API’s documentation. Consider adding delays (Await Blocks) between requests if needed.

Can I make requests to internal/private APIs?

This depends on your bot’s hosting environment. Ensure the bot can reach the API endpoint (no firewall blocks, correct network access).

How do I debug failed requests?

1. Use the Test Request feature to see actual responses
2. Check test result for error messages
3. Verify URL, headers, and authentication
4. Use Alert Blocks to log request failures
5. Check external API’s logs if available