Skip to main content

Destinations

Destinations are the endpoints where Hooklistener forwards webhooks after they've been received, processed, and optionally transformed. Each Destination represents a target service, URL, or integration where your webhook data should be delivered.

Overview​

A Destination defines where and how webhooks should be sent once they arrive at a Source. Hooklistener supports multiple destination types, from simple HTTP endpoints to integrated services like Slack, Discord, and Telegram.

Key features:

  • Multiple destination types: HTTP/HTTPS, Slack, Discord, Telegram, and more
  • Retry logic: Automatic retries with exponential backoff for failed deliveries
  • Circuit breakers: Automatic protection against cascading failures
  • Custom headers: Add authentication, API keys, or custom metadata
  • Transformations: Modify payloads before delivery
  • Filters: Conditionally route webhooks based on content
  • Delivery tracking: Monitor success, failures, and retry attempts

Destination Types​

HTTP/HTTPS Destinations​

The most flexible destination type - send webhooks to any HTTP endpoint.

Configuration:

{
  "name": "My API Endpoint",
  "type": "http",
  "url": "https://api.example.com/webhooks",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer {{API_TOKEN}}",
    "Content-Type": "application/json"
  }
}

Features:

  • Support for any HTTP method (POST, PUT, PATCH, GET)
  • Custom headers with secret substitution
  • Query parameter support
  • Request timeout configuration
  • SSL/TLS certificate validation

Use cases:

  • Internal APIs
  • Third-party services without native integration
  • Custom webhook processors
  • Serverless functions (AWS Lambda, Google Cloud Functions, etc.)

Slack Destinations​

Send formatted messages directly to Slack channels.

Configuration:

{
  "name": "Alerts Channel",
  "type": "slack",
  "webhook_url": "{{SLACK_WEBHOOK_URL}}"
}

Features:

  • Rich message formatting with Slack Block Kit
  • Automatic markdown conversion
  • Mention support (@channel, @here, @user)
  • Thread support
  • Emoji reactions

Use cases:

  • Alert notifications
  • Build status updates
  • Customer activity feeds
  • System monitoring alerts

Discord Destinations​

Post messages to Discord channels via webhooks.

Configuration:

{
  "name": "Development Updates",
  "type": "discord",
  "webhook_url": "{{DISCORD_WEBHOOK_URL}}"
}

Features:

  • Embed support for rich content
  • Username and avatar customization
  • Mention notifications
  • File attachments
  • Thread creation

Use cases:

  • Team notifications
  • Bot integrations
  • Community updates
  • Server monitoring

Telegram Destinations​

Send messages to Telegram chats or channels.

Configuration:

{
  "name": "Admin Notifications",
  "type": "telegram",
  "bot_token": "{{TELEGRAM_BOT_TOKEN}}",
  "chat_id": "{{TELEGRAM_CHAT_ID}}"
}

Features:

  • HTML and Markdown formatting
  • Inline keyboards
  • File and media support
  • Silent notifications
  • Reply markup

Use cases:

  • Personal notifications
  • Alert systems
  • Bot commands
  • Monitoring dashboards

Creating a Destination​

Via Dashboard​

  1. Navigate to Destinations in the sidebar
  2. Click "Create Destination"
  3. Choose your destination type (HTTP, Slack, Discord, Telegram)
  4. Configure the destination settings:
    • Name: Descriptive identifier (e.g., "Production API", "Slack Alerts")
    • URL/Endpoint: Where webhooks should be sent
    • Headers: Custom headers including authentication
    • Settings: Type-specific configuration
  5. Click "Create"

Via API​

curl -X POST https://api.hooklistener.com/api/v1/bridges \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Bridge",
    "source": {
      "type": "webhook"
    },
    "destinations": [{
      "name": "Production API",
      "type": "http",
      "url": "https://api.example.com/webhooks",
      "headers": {
        "Authorization": "Bearer {{API_TOKEN}}"
      }
    }]
  }'

Destination Configuration​

URL and Endpoint Settings​

Static URLs

https://api.example.com/webhooks

Dynamic URLs with Secrets

https://api.telegram.org/bot{{TELEGRAM_BOT_TOKEN}}/sendMessage
https://hooks.slack.com/services/{{SLACK_WEBHOOK_PATH}}

Query Parameters

https://api.example.com/webhook?api_key=\{\{API_KEY\}\}&source=hooklistener

Custom Headers​

Headers are sent with every webhook delivery and support secret substitution:

{
  "headers": {
    "Authorization": "Bearer {{API_TOKEN}}",
    "X-API-Key": "\{\{API_KEY\}\}",
    "X-Webhook-Source": "hooklistener",
    "Content-Type": "application/json",
    "User-Agent": "Hooklistener/1.0"
  }
}

Common header use cases:

  • Authentication: API keys, Bearer tokens, Basic auth
  • Content negotiation: Content-Type, Accept headers
  • Tracking: Custom identifiers, correlation IDs
  • Security: HMAC signatures, API versioning

Retry Configuration​

Control how Hooklistener handles failed deliveries:

Max Retries: Number of retry attempts (default: 15)

{
  "max_retries": 15
}

Retry Strategy: Exponential backoff schedule

  • 1st retry: ~1 minute
  • 2nd retry: ~2 minutes
  • 3rd retry: ~4 minutes
  • ...continues exponentially up to max retries

Retry Conditions: When to retry

  • Network errors (timeouts, connection refused)
  • HTTP 5xx errors (server errors)
  • HTTP 429 (rate limiting)

No retry for:

  • HTTP 4xx errors (except 429)
  • Invalid URLs
  • Authentication failures

Circuit Breaker Protection​

Destinations are automatically protected by circuit breakers to prevent cascading failures:

States:

  • Closed: Normal operation, all requests allowed
  • Open: Too many failures, requests blocked temporarily
  • Half-open: Testing if service recovered

Configuration:

  • Failure threshold: 5 failures within 60 seconds
  • Recovery timeout: 60 seconds before testing again
  • Success threshold: 2 successful requests to close circuit

See Circuit Breakers for detailed information.

Transformations​

Transform webhook payloads before delivery using JavaScript:

addHandler('transform', async (request, context) => {
  // Modify the payload for this destination
  const payload = {
    event_type: request.body.type,
    timestamp: new Date().toISOString(),
    data: request.body
  };

  return {
    ...request,
    body: payload
  };
});

Transformations enable:

  • Format conversion (adapt incompatible APIs)
  • Data enrichment (add metadata, timestamps)
  • Payload filtering (remove sensitive data)
  • Custom authentication (inject signatures, tokens)

See Transformations for detailed guides.

Filters​

Route webhooks conditionally based on payload content:

{
  "filters": [
    {
      "body.event_type": { "$eq": "payment.succeeded" }
    },
    {
      "body.amount": { "$gte": 10000 }
    }
  ]
}

Only webhooks matching all filter conditions will be forwarded to this destination.

See Filters for filter syntax and examples.

Monitoring Destinations​

Delivery Statistics​

Track destination performance in the dashboard:

Success Rate: Percentage of successful deliveries

  • Target: >99% for production systems
  • Investigate if falling below 95%

Response Times: Average, p50, p95, p99 latencies

  • Monitor for degradation
  • Set alerts for slowdowns

Error Rates: Failed deliveries and common error codes

  • 4xx errors: Check authentication and payload format
  • 5xx errors: Destination service issues
  • Timeouts: Network or performance problems

Circuit Breaker Status​

Monitor circuit breaker state for each destination:

  • Healthy (Closed): Operating normally
  • Degraded (Half-open): Recovering from failures
  • Failing (Open): Too many errors, temporarily blocked

Reset circuit breakers manually if needed:

curl -X POST https://api.hooklistener.com/api/v1/circuit-breakers/{destination_id}/reset \
  -H "Authorization: Bearer YOUR_API_KEY"

Event History​

View complete delivery history:

  • Request details (headers, body, method)
  • Response details (status code, headers, body)
  • Retry attempts and outcomes
  • Transformation logs
  • Filter evaluation results

Best Practices​

Security​

  1. Use secrets for sensitive data

    • Store API keys, tokens in Hooklistener Secrets
    • Reference with {{SECRET_NAME}} syntax
    • Never hardcode credentials in URLs or headers

  2. Validate SSL certificates

    • Ensure destination endpoints use valid HTTPS
    • Avoid self-signed certificates in production
    • Monitor certificate expiration

  3. Implement authentication

    • Use API keys, Bearer tokens, or HMAC signatures
    • Rotate credentials regularly
    • Monitor authentication failures

Reliability​

  1. Configure appropriate retries

    • Use default 15 retries for critical deliveries
    • Reduce retries for non-critical or idempotent operations
    • Consider destination SLA when setting retries

  2. Monitor circuit breakers

    • Set up alerts for open circuits
    • Investigate root causes quickly
    • Test destinations before resetting circuits

  3. Handle errors gracefully

    • Design destinations to be idempotent
    • Implement proper error handling on receiver side
    • Log and monitor delivery failures

Performance​

  1. Optimize destination endpoints

    • Keep response times under 5 seconds
    • Return quickly (process asynchronously if needed)
    • Handle high request volumes

  2. Use transformations wisely

    • Keep transformation code simple and fast
    • Avoid heavy computations or large data structures
    • Test transformations before deploying

  3. Monitor latency

    • Track p95 and p99 response times
    • Set alerts for degradation
    • Investigate slow destinations

Organization​

  1. Use descriptive names

    • Include environment: "Production API", "Staging Slack"
    • Specify purpose: "Payment Alerts", "Build Notifications"
    • Add context: "Customer Portal - User Events"

  2. Group related destinations

    • Separate production and development
    • Organize by service or team
    • Use consistent naming conventions

  3. Document configurations

    • Note special requirements or dependencies
    • Link to external service documentation
    • Track configuration changes

Troubleshooting​

Delivery Failures​

Check destination availability

# Test the endpoint directly
curl -X POST https://api.example.com/webhooks \
  -H "Content-Type: application/json" \
  -d '{"test": "payload"}'

Review error responses

  • 400 Bad Request: Check payload format
  • 401 Unauthorized: Verify authentication headers
  • 403 Forbidden: Check API permissions
  • 404 Not Found: Verify URL is correct
  • 429 Too Many Requests: Review rate limiting
  • 500+ Server Error: Destination service issues

Check circuit breaker state

  • If open, wait for automatic recovery or reset manually
  • Review failure patterns in event history
  • Verify destination service is operational

Authentication Issues​

Invalid API keys or tokens

  • Verify secret values are correct
  • Check secret names match exactly ({{API_KEY}} vs {{API_TOKEN}})
  • Ensure secrets are active (not deleted)

Header format errors

  • Check header name capitalization
  • Verify Bearer/Basic prefix is correct
  • Review required vs optional headers

Transformation Errors​

Syntax errors

  • Validate JavaScript code syntax
  • Test transformation in isolation
  • Check for missing return statements

Runtime errors

  • Review transformation logs
  • Check for undefined variables
  • Verify payload structure assumptions

Timeout errors

  • Simplify transformation logic
  • Remove heavy computations
  • Reduce data processing

Performance Issues​

Slow deliveries

  • Check destination service response times
  • Review network connectivity
  • Investigate destination endpoint performance

Timeout errors

  • Increase timeout if destination is legitimately slow
  • Optimize destination endpoint
  • Consider async processing on destination side

High retry rates

  • Investigate root cause of failures
  • Check destination service health
  • Review retry configuration

Integration Examples​

Internal API​

{
  "name": "Internal Webhook Processor",
  "type": "http",
  "url": "https://internal-api.company.com/webhooks",
  "method": "POST",
  "headers": {
    "Authorization": "Bearer {{INTERNAL_API_TOKEN}}",
    "X-Source": "hooklistener",
    "Content-Type": "application/json"
  },
  "max_retries": 15
}

Slack Notification​

{
  "name": "Production Alerts",
  "type": "slack",
  "webhook_url": "{{SLACK_WEBHOOK_URL}}",
  "max_retries": 5
}

Serverless Function​

{
  "name": "AWS Lambda Processor",
  "type": "http",
  "url": "https://xyz123.execute-api.us-east-1.amazonaws.com/prod/webhook",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{AWS_API_KEY}}"
  },
  "max_retries": 10
}

Next Steps​

Now that you understand Destinations, learn how to:

  1. Build Bridges to connect Sources and Destinations
  2. Configure Filters to route webhooks conditionally
  3. Use Transformations to modify payloads
  4. Monitor Circuit Breakers for reliability
  5. Track Issues to resolve delivery problems

Destinations are where your webhook data ultimately lands. By properly configuring destinations with security, reliability, and monitoring in mind, you ensure your webhook workflows operate smoothly and efficiently.