Destinations API

Destinations are endpoints where webhooks get delivered.

Endpoints

Method	Path	Description
GET	/api/organizations/{orgId}/destinations	List destinations
POST	/api/organizations/{orgId}/destinations	Create destination
GET	/api/organizations/{orgId}/destinations/{id}	Get destination
PATCH	/api/organizations/{orgId}/destinations/{id}	Update destination
DELETE	/api/organizations/{orgId}/destinations/{id}	Delete destination

Destination Object

{
  "id": "dst_xyz789",
  "name": "Production API",
  "url": "https://api.yourapp.com/webhooks",
  "description": "Main webhook handler",
  "headers": {
    "Authorization": "Bearer sk_live_xxx",
    "X-Custom-Header": "value"
  },
  "retryPolicy": {
    "maxRetries": 5,
    "initialDelay": 1000,
    "maxDelay": 60000,
    "backoffMultiplier": 2
  },
  "enabled": true,
  "successRate": 98.5,
  "avgLatency": 245,
  "deliveriesCount": 5230,
  "lastDeliveryAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

List Destinations

GET /api/organizations/{orgId}/destinations

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
pageSize	number	Items per page (default: 20, max: 100)
enabled	boolean	Filter by enabled status
search	string	Search by name or URL

Example

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

Response

{
  "data": [
    {
      "id": "dst_xyz789",
      "name": "Production API",
      "url": "https://api.yourapp.com/webhooks",
      "enabled": true,
      "successRate": 98.5,
      "avgLatency": 245,
      "deliveriesCount": 5230
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "pageSize": 20
  }
}

Create Destination

POST /api/organizations/{orgId}/destinations

Request Body

Field	Type	Required	Description
name	string	Yes	Display name
url	string	Yes	Delivery URL (HTTPS recommended)
description	string	No	Optional description
headers	object	No	Custom headers to include
retryPolicy	object	No	Retry configuration
enabled	boolean	No	Active status (default: true)

Retry Policy

Field	Type	Default	Description
maxRetries	number	5	Max retry attempts
initialDelay	number	1000	First retry delay (ms)
maxDelay	number	60000	Max delay between retries (ms)
backoffMultiplier	number	2	Exponential backoff multiplier

Example

curl -X POST https://api.webhookrelay.com/api/organizations/org_123/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-Source": "webhookrelay"
    },
    "retryPolicy": {
      "maxRetries": 5,
      "initialDelay": 1000,
      "maxDelay": 300000
    }
  }'

Response

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

Get Destination

GET /api/organizations/{orgId}/destinations/{id}

Example

curl https://api.webhookrelay.com/api/organizations/org_123/destinations/dst_xyz789 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

Returns the full destination object.

Update Destination

PATCH /api/organizations/{orgId}/destinations/{id}

Request Body

All fields are optional. Only provided fields are updated.

Field	Type	Description
name	string	Display name
url	string	Delivery URL
description	string	Optional description
headers	object	Custom headers (replaces existing)
retryPolicy	object	Retry configuration
enabled	boolean	Active status

Example

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

Response

Returns the updated destination object.

Delete Destination

DELETE /api/organizations/{orgId}/destinations/{id}

WARNING

Deleting a destination removes it from all routes. Deliveries are preserved for history.

Example

curl -X DELETE https://api.webhookrelay.com/api/organizations/org_123/destinations/dst_xyz789 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

204 No Content

Destination Health

Get health metrics for a destination:

GET /api/organizations/{orgId}/destinations/{id}/health

Response

{
  "successRate": 98.5,
  "avgLatency": 245,
  "p50Latency": 180,
  "p95Latency": 450,
  "p99Latency": 890,
  "totalDeliveries": 5230,
  "successfulDeliveries": 5152,
  "failedDeliveries": 78,
  "lastDeliveryAt": "2024-01-15T10:30:00Z",
  "lastSuccessAt": "2024-01-15T10:30:00Z",
  "lastFailureAt": "2024-01-15T09:15:00Z",
  "status": "healthy"
}

Status Values

Status	Description
healthy	Success rate > 95%
degraded	Success rate 80-95%
failing	Success rate < 80%
unknown	No recent deliveries

Error Responses

400 Bad Request

Invalid URL:

{
  "error": "Bad Request",
  "message": "Invalid URL format",
  "code": "INVALID_URL"
}

404 Not Found

Destination not found:

{
  "error": "Not Found",
  "message": "Destination with ID dst_xyz not found",
  "code": "RESOURCE_NOT_FOUND"
}