Skip to Content
BuildWebhook Integration

Webhook Integration

Trame provides custom webhook endpoints that allow external systems to trigger workflows directly. Each workflow can have its own unique webhook URL, enabling seamless integration with third-party services, custom applications, and external automation systems.

Webhook Basics

How Webhooks Work

Webhooks enable external systems to trigger Trame workflows by making HTTP POST requests to unique URLs:

  1. Workflow Creation: Each workflow automatically gets a unique webhook endpoint
  2. External Integration: Third-party systems send HTTP POST requests to the webhook URL
  3. Trigger Processing: Trame receives the request and starts the workflow
  4. Data Flow: Request payload becomes available as input data for the workflow
  5. Response: Trame returns appropriate HTTP status codes and response data

Webhook URLs

Each workflow webhook URL follows this pattern:

https://tramehq.com/api/hooks/{webhookSlug}

Where webhookSlug is a unique, readable identifier like invoice-processor-k3m9 or support-escalation-x7p2.

Security Features

  • Unique URLs: Each workflow gets a cryptographically unique endpoint
  • Optional Secrets: Workflows can include webhook secrets for signature verification
  • Organization Isolation: Webhooks are scoped to the owning organization
  • Request Validation: Incoming requests are validated before workflow execution

Setting Up Webhooks

Enabling Webhook Triggers

  1. Create or Edit Workflow: Navigate to your workflow in the Trame interface
  2. Configure Trigger: Select “Webhook” as the trigger type during creation or editing
  3. Automatic Generation: Trame automatically generates a unique webhook URL and slug
  4. Copy Webhook URL: Use the provided URL to configure external systems
  5. Optional Security: Configure webhook secret for additional security

Webhook Configuration

Each webhook includes:

  • Webhook Slug: Human-readable unique identifier (e.g., customer-onboarding-m4x9)
  • Full URL: Complete webhook endpoint URL for external systems
  • Optional Secret: Shared secret for HMAC signature verification
  • Request Method: Currently supports HTTP POST requests only
  • Content-Type: Accepts application/json and application/x-www-form-urlencoded

Security Configuration

For enhanced security, configure webhook secrets:

  1. Generate Secret: Create a secure random string or use Trame’s generator
  2. Share with External System: Configure the secret in your external system
  3. Signature Verification: External systems should include HMAC signatures in headers
  4. Validation: Trame validates signatures before processing requests

Webhook Request Format

HTTP Request Structure

External systems should send POST requests with:

POST /api/hooks/{webhookSlug}
Content-Type: application/json
X-Webhook-Signature: sha256=<hmac_signature>
 
{
  "event": "order.created",
  "orderId": "ORD-12345",
  "customer": {
    "email": "customer@example.com",
    "name": "John Smith"
  },
  "amount": 299.99,
  "timestamp": "2024-01-15T10:30:00Z"
}

Supported Content Types

  • application/json: JSON payload (recommended)
  • application/x-www-form-urlencoded: Form-encoded data
  • text/plain: Plain text content (for simple integrations)

Request Headers

Important headers for webhook requests:

  • Content-Type: Specifies the payload format
  • X-Webhook-Signature: HMAC signature for verification (if secret is configured)
  • User-Agent: Identifies the sending system (helpful for debugging)
  • X-Event-Type: Optional event type identifier for filtering

Payload Processing

Data Access in Workflows

Webhook payload data is available to workflows through:

  • Input Data: Complete request payload accessible as structured data
  • Headers: Request headers available for conditional logic
  • Metadata: Timestamp, source IP, and request metadata

Data Types and Formats

Trame automatically handles:

  • JSON Objects: Parsed into structured data for workflow use
  • Arrays: Lists and collections of data items
  • Primitive Values: Strings, numbers, booleans, and null values
  • Nested Data: Complex nested objects and arrays

Data Validation

Built-in validation includes:

  • Schema Validation: Optional JSON schema validation for payload structure
  • Required Fields: Ensure critical data is present before execution
  • Data Type Checking: Validate data types match expectations
  • Size Limits: Prevent oversized payloads from consuming resources

Integration Examples

E-commerce Platform

{
  "event_type": "order.created",
  "order": {
    "id": "order_123456",
    "status": "pending",
    "total": 159.99,
    "currency": "USD",
    "customer": {
      "email": "buyer@example.com",
      "phone": "+1-555-0123"
    }
  }
}

Workflow Actions:

  • Send order confirmation email
  • Create shipping label
  • Update inventory
  • Notify fulfillment team

CRM Integration

{
  "event": "lead.qualified",
  "lead": {
    "id": "lead_789012",
    "email": "prospect@company.com",
    "company": "Acme Corp",
    "score": 85,
    "source": "web_form"
  }
}

Workflow Actions:

  • Assign to sales rep
  • Create opportunity in CRM
  • Send welcome sequence
  • Schedule follow-up call

Support System

{
  "event": "ticket.urgent",
  "ticket": {
    "id": "TKT-456789",
    "priority": "high",
    "customer": {
      "tier": "enterprise",
      "email": "support@bigclient.com"
    },
    "subject": "Production system down"
  }
}

Workflow Actions:

  • Escalate to senior support
  • Create incident in monitoring system
  • Notify engineering team
  • Start incident response process

Response Handling

HTTP Status Codes

Trame returns appropriate status codes:

  • 200 OK: Webhook processed successfully, workflow started
  • 202 Accepted: Webhook queued for processing
  • 400 Bad Request: Invalid payload or malformed request
  • 401 Unauthorized: Invalid or missing webhook secret
  • 404 Not Found: Webhook URL not found or workflow deleted
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: System error during processing

Response Bodies

Success responses include:

{
  "status": "accepted",
  "workflowId": "wfl_abc123",
  "executionId": "exec_def456",
  "message": "Workflow execution started"
}

Error responses include:

{
  "error": "invalid_payload",
  "message": "Required field 'customer.email' is missing",
  "code": "VALIDATION_ERROR"
}

Security Best Practices

Webhook Secret Implementation

For maximum security, implement webhook secrets:

  1. Generate Strong Secrets: Use cryptographically secure random strings
  2. HMAC Signatures: Include HMAC-SHA256 signatures in request headers
  3. Signature Verification: Validate signatures before trusting payload data
  4. Secret Rotation: Regularly rotate webhook secrets for security

Example Signature Generation (Node.js)

const crypto = require('crypto');
 
function generateSignature(payload, secret) {
  return 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
}

Network Security

  • HTTPS Only: Trame webhooks only accept HTTPS requests
  • IP Allowlisting: Configure firewall rules for known source IPs
  • Rate Limiting: Built-in protection against webhook spam
  • Request Size Limits: Payload size restrictions prevent abuse

Monitoring and Debugging

Webhook Logs

Monitor webhook activity through:

  • Request Logs: Complete record of incoming webhook requests
  • Success/Failure Rates: Track webhook reliability over time
  • Response Times: Monitor webhook processing performance
  • Error Analysis: Detailed error logs for troubleshooting

Common Issues and Solutions

Webhook Not Triggering

  • Verify URL: Ensure external system uses correct webhook URL
  • Check Workflow Status: Paused workflows ignore webhook triggers
  • Validate Payload: Malformed JSON or data may prevent processing
  • Review Logs: Check webhook logs for error messages

Authentication Failures

  • Secret Mismatch: Verify webhook secret matches between systems
  • Signature Format: Ensure HMAC signature header format is correct
  • Character Encoding: Check for encoding issues in secret or payload

Payload Processing Errors

  • Required Fields: Ensure all required data fields are present
  • Data Types: Validate data types match workflow expectations
  • Size Limits: Check that payloads don’t exceed size restrictions

Advanced Configuration

Conditional Execution

Configure workflows to execute conditionally based on webhook data:

  • Event Filtering: Only process specific event types
  • Data Conditions: Execute based on payload field values
  • Business Rules: Apply organizational logic to webhook processing

Error Handling

Configure how workflows handle webhook processing errors:

  • Retry Logic: Automatic retries for transient failures
  • Error Notifications: Alert administrators of processing issues
  • Fallback Workflows: Alternative workflows for error scenarios

Performance Optimization

  • Async Processing: Webhook requests are processed asynchronously
  • Batching: Group related webhook events for efficient processing
  • Caching: Cache frequently accessed data for better performance

Integration Patterns

Event-Driven Architecture

Use webhooks to implement event-driven patterns:

  • Event Sourcing: Process state changes as discrete events
  • Message Routing: Route events to appropriate workflows
  • Pub/Sub Patterns: Webhook as subscriber in publish/subscribe systems

Microservices Integration

Connect microservices through webhook events:

  • Service Decoupling: Loose coupling between services via webhooks
  • Cross-Service Workflows: Orchestrate actions across multiple services
  • Event Propagation: Share events across service boundaries

Third-Party Integration

Common third-party webhook sources:

  • Payment Processors: Stripe, PayPal, Square payment events
  • E-commerce Platforms: Shopify, WooCommerce order events
  • CRM Systems: Salesforce, HubSpot, Pipedrive contact events
  • Communication Tools: Slack, Discord, Teams message events
  • Monitoring Systems: PagerDuty, DataDog alert events
Last updated on
Triggers & webhooksWorkflows