HTTP Webhook Integration for PromptlyAgent AI

Powerful HTTP webhook output action provider for the PromptlyAgent AI Research Assistant. Send structured HTTP requests to external services when your agents or input triggers complete execution, enabling seamless workflow automation and integration with external systems.

Screenshots

Configuration Interface

Configure HTTP webhook output actions through the PromptlyAgent admin interface:

Webhook URL, HTTP method, and timeout settings

Custom headers and JSON body template with variable substitution

Expression syntax, placeholders, and security patterns

Manual testing interface and execution logs

Features

• Flexible HTTP Methods: Support for GET, POST, PUT, PATCH, DELETE
• Template System: Dynamic variable substitution with {{variable}} syntax
• Expression Language: Advanced expressions with ${expression} for timestamps, encoding, hashing, and HMAC signatures
• HMAC Security: Built-in support for webhook signature generation (GitHub, Stripe, Slack patterns)
• Workflow Chaining: Trigger other PromptlyAgent agents via webhook input triggers
• Reliable Execution: Queue-based execution with comprehensive logging
• Timeout Control: Configurable request timeouts (1-120 seconds)
• Custom Headers: Full header customization with template support

Installation

Via Composer (Local Development)

composer require promptlyagentai/http-webhook-integration:@dev

The package will automatically register itself via Laravel's package discovery.

Quick Start

1. Navigate to Settings → Integrations in your PromptlyAgent application
2. Find "Output Webhook" in the available integrations
3. Click Setup to create a new webhook action
4. Configure:
   • Name: Descriptive name for this webhook
   • Webhook URL: The endpoint to send requests to
   • HTTP Method: Choose GET, POST, PUT, PATCH, or DELETE
   • Request Headers: Optional JSON object with custom headers
   • Request Body: JSON template for the payload
   • Timeout: Request timeout in seconds (1-120)

Template Syntax

Simple Variables: {{variable}}

Use double curly braces for simple variable substitution:

{
  "result": {{result_encoded}},
  "session": "{{session_id}}",
  "agent": "{{agent_name_escaped}}",
  "status": "{{status}}"
}

Available Variables:

• {{result}} - Agent execution result (raw)
• {{result_encoded}} - JSON-encoded with quotes (use as standalone value)
• {{result_escaped}} - Escaped without quotes (use for embedding in strings)
• {{session_id}} - Chat session ID
• {{execution_id}} - Unique execution ID
• {{user_id}} - User who triggered the action
• {{agent_id}} / {{agent_name}} - Agent details
• {{trigger_id}} / {{trigger_name}} - Input trigger details
• {{status}} - Execution status (success/failed)
• {{timestamp}} - Unix timestamp (generated once)
• {{nonce}} - UUID v4 nonce (generated once)
• {{secret}} - Webhook secret (if configured)
• {{body}} - Serialized request body (for signatures)

Expressions: ${expression}

Use dollar-brace syntax for dynamic expressions:

Timestamp Functions:

${timestamp()}           // Unix timestamp
${timestamp_iso()}       // ISO 8601 timestamp
${format_timestamp("Y-m-d H:i:s")}  // Custom format

UUID Generation:

${uuid()}                // Generate UUID v4

Encoding Functions:

${base64(result)}        // Base64 encode
${url_encode(result)}    // URL encode
${json_encode(result)}   // JSON encode

Hashing Functions:

${hash("sha256", body)}  // Hash with algorithm
${md5(body)}             // MD5 hash
${sha256(body)}          // SHA-256 hash

HMAC Signatures:

${hmac(body, secret)}              // HMAC-SHA256
${hmac(body, secret, "sha1")}      // HMAC with custom algorithm

String Functions:

${lower(result)}         // Lowercase
${upper(result)}         // Uppercase
${trim(result)}          // Trim whitespace
${concat("prefix-", session_id)}  // Concatenate strings

Security Patterns

GitHub-Style Signature

{
  "Content-Type": "application/json",
  "X-Hub-Signature-256": "sha256=${hmac(body, secret)}"
}

Stripe-Style Timestamped Signature

{
  "Content-Type": "application/json",
  "Stripe-Signature": "t={{timestamp}},v1=${hmac(concat(timestamp, '.', body), secret)}"
}

Important: Use {{timestamp}} variable (not ${timestamp()}) to reuse the same value!

Workflow Chaining

Chain agents together by triggering PromptlyAgent webhook input triggers:

URL:

http://laravel.test/webhooks/triggers/{trigger-id}

Headers:

{
  "Content-Type": "application/json",
  "X-Trigger-Signature": "${hmac(concat(timestamp, nonce, body), secret)}",
  "X-Trigger-Timestamp": "{{timestamp}}",
  "X-Trigger-Nonce": "{{nonce}}"
}

Body:

{
  "text": {{result_encoded}},
  "metadata": {
    "source_agent": "{{agent_name_escaped}}",
    "source_session": "{{session_id}}"
  }
}

Configure the webhook secret in your input trigger settings to enable secure signature validation.

Example Configurations

Basic Webhook

{
  "event": "agent_completed",
  "result": {{result_encoded}},
  "session_id": "{{session_id}}",
  "timestamp": "${timestamp_iso()}"
}

Secure Webhook with HMAC

{
  "event": "agent_completed",
  "data": {
    "result": {{result_encoded}},
    "session": "{{session_id}}"
  },
  "metadata": {
    "timestamp": "{{timestamp}}",
    "signature": "${hmac(body, secret)}"
  }
}

Architecture

This package follows the PromptlyAgent integration pattern:

Core Components

• Provider: HttpOutputActionProvider - Implements OutputActionProvider contract
• Services: ExpressionEvaluator - Safe expression evaluation engine
• Integration: Registers with OutputActionRegistry and ProviderRegistry

Package Structure

src/
├── HttpWebhookServiceProvider.php   # Main service provider
├── Providers/
│   └── HttpOutputActionProvider.php # HTTP webhook implementation
└── Services/
    └── ExpressionEvaluator.php      # Expression evaluation

Customization & Forking

This package is designed to be forked and customized:

1. Custom Expressions: Add new functions to ExpressionEvaluator service to support additional transformation logic
2. Authentication: Extend HttpOutputActionProvider to add OAuth/JWT authentication flows
3. Retry Logic: Override the execute() method to implement exponential backoff or custom retry strategies
4. Rate Limiting: Add rate limiting middleware or throttling logic to the provider

Fork this repository and modify the source code to fit your specific integration requirements.

Requirements

• PHP 8.2 or higher
• Laravel 11.0 or 12.0
• Symfony Expression Language 7.0 or 8.0

Testing

# Run all tests
./vendor/bin/pest

# Test specific file
./vendor/bin/pest tests/Feature/HttpOutputActionProviderTest.php

Contributing

This package is part of the PromptlyAgent AI ecosystem. For contributions, please refer to the main repository guidelines.

License

The MIT License (MIT). Please see License File for more information.

Credits

• PromptlyAgent AI Team
• Built with Laravel and Symfony Expression Language

Support

For issues and questions:

• GitHub Issues: promptlyagentai/http-webhook-integration
• Email: hello@promptlyagent.ai