Destinations

Destinations are the endpoints where webhooks get delivered after processing.

Overview

A destination represents your application's webhook handler. When a webhook arrives at a source and matches a route, WebhookRelay delivers it to all connected destinations.

Creating a Destination

Required Fields

Field	Description
name	Human-readable name
url	The HTTP(S) URL to deliver webhooks to

Optional Fields

Field	Description
description	Optional description
headers	Custom headers to include in requests
retryPolicy	Configuration for retry behavior
enabled	Whether the destination is active (default: true)

Custom Headers

Add custom headers to every webhook delivery:

{
  "headers": {
    "Authorization": "Bearer your-api-key",
    "X-Custom-Header": "custom-value",
    "X-Source": "webhookrelay"
  }
}

Common use cases:

• Authentication tokens
• API keys
• Tracking headers
• Environment identifiers

Retry Policy

Configure how WebhookRelay handles failed deliveries:

{
  "retryPolicy": {
    "maxRetries": 5,
    "initialDelay": 1000,
    "maxDelay": 60000,
    "backoffMultiplier": 2
  }
}

Field	Description	Default
maxRetries	Maximum number of retry attempts	5
initialDelay	First retry delay in milliseconds	1000
maxDelay	Maximum delay between retries	60000
backoffMultiplier	Multiplier for exponential backoff	2

Retry Schedule Example

With default settings, retries occur at:

1. Immediate delivery attempt
2. 1 second later
3. 2 seconds later
4. 4 seconds later
5. 8 seconds later
6. 16 seconds later (if max 5 retries)

Success Criteria

A delivery is considered successful when:

• HTTP status code is 2xx (200-299)
• Response is received within timeout (30 seconds)

Failure Handling

After all retries are exhausted:

• The delivery is marked as failed
• The event is moved to the dead letter queue
• You can manually replay from the dashboard

Example: Creating a Destination

curl -X POST https://api.webhookrelay.com/api/organizations/{orgId}/destinations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "url": "https://api.yourapp.com/webhooks/handler",
    "headers": {
      "Authorization": "Bearer sk_live_xxx",
      "X-Webhook-Source": "webhookrelay"
    },
    "retryPolicy": {
      "maxRetries": 5,
      "initialDelay": 1000,
      "maxDelay": 300000
    }
  }'

Response:

{
  "id": "dst_xyz789",
  "name": "Production API",
  "url": "https://api.yourapp.com/webhooks/handler",
  "headers": {
    "Authorization": "Bearer sk_live_xxx",
    "X-Webhook-Source": "webhookrelay"
  },
  "retryPolicy": {
    "maxRetries": 5,
    "initialDelay": 1000,
    "maxDelay": 300000,
    "backoffMultiplier": 2
  },
  "enabled": true,
  "createdAt": "2024-01-15T10:30:00Z"
}

Managing Destinations

List Destinations

curl https://api.webhookrelay.com/api/organizations/{orgId}/destinations \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Destination Details

curl https://api.webhookrelay.com/api/organizations/{orgId}/destinations/{destinationId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Destination

curl -X PATCH https://api.webhookrelay.com/api/organizations/{orgId}/destinations/{destinationId} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/v2/handler"
  }'

Delete Destination

curl -X DELETE https://api.webhookrelay.com/api/organizations/{orgId}/destinations/{destinationId} \
  -H "Authorization: Bearer YOUR_TOKEN"

Destination Health

Monitor destination health in the dashboard:

• Success Rate: Percentage of successful deliveries
• Average Latency: Mean response time
• Last Delivery: Timestamp of most recent delivery
• Status: Active, degraded, or failing

Best Practices

1. Use HTTPS: Always use HTTPS URLs for production destinations

2. Set appropriate timeouts: Ensure your endpoint responds within 30 seconds

3. Return 2xx quickly: Acknowledge receipt quickly, process asynchronously if needed

4. Handle duplicates: Webhooks may be delivered more than once; implement idempotency

5. Monitor health: Set up alerts for destinations with high failure rates

6. Use staging destinations: Test changes with a staging destination before production

Troubleshooting

Destination shows high failure rate

1. Check if the destination URL is accessible
2. Verify authentication headers are correct
3. Check your application logs for errors
4. Use the Event Debugger to inspect request/response

Webhooks not being delivered

1. Verify the destination is enabled
2. Check if routes are configured correctly
3. Ensure filters aren't blocking events
4. Check the dead letter queue for failed deliveries