Destinations API | HookDeploy

HookDeploy has two destination layers:

Saved destinations (library) — reusable HTTPS URL templates at the organization level (/v1/destinations). Agent targets cannot be saved or reused; they are endpoint-specific forward destinations only.
Forward destinations — per-endpoint targets used at forward time (/v1/endpoints/:id/destinations). Each forward destination is either HTTPS (destination_type: "https") or agent (destination_type: "agent"), never both.

Creating saved destinations or HTTPS forward attachments requires an API key whose role has endpoints.edit (typically super_admin, admin, or developer). Creating agent forward destinations additionally requires agents.assign_destination on the same roles (viewer cannot assign agents).

Destination types (stored shape)

Type	`destination_type`	Required fields	Notes
HTTPS	`"https"`	`url` (`https://…`)	`agent_id`, `target_port`, `target_path` are always `null`
Agent	`"agent"`	`agent_id`, `target_port` (1–65535), `target_path` (must start with `/`)	`url` is always `null`. No host is stored — only loopback port and path on the enrolled machine. Optional `environment_override`: `"development"` only (downgrade-only; inherits agent environment when omitted).

Agent destinations dial out through an enrolled HookDeploy agent. The agent must belong to the same organization as the endpoint.

Create destination

POST /v1/destinations

Behavior depends on destination_type. When omitted, it defaults to https (saved-destination flow).

HTTPS saved destination (default)

Creates a reusable saved destination. If endpoint_id is present, also attaches it as an HTTPS forward destination on that endpoint.

curl -s -X POST \
  "https://api.hookdeploy.dev/v1/destinations" \
  -H "Authorization: Bearer hd_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Webhook",
    "url": "https://myserver.com/webhooks",
    "endpoint_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Body fields (HTTPS / saved):

Field	Required	Description
`name`	yes	Display name
`url`	yes	Target URL (`https://…`)
`destination_type`	no	Omit or `"https"`
`endpoint_id`	no	If set, also creates a forward destination on that endpoint
`visibility`	no	`private`, `org`, or `restricted`
`is_reusable`	no	Boolean (defaults to reusable library entry)

Success (201) — saved destination shape:

{
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "name": "Production Webhook",
    "url": "https://myserver.com/webhooks",
    "visibility": "private",
    "is_reusable": true,
    "created_at": "2026-05-24T12:00:00Z",
    "forward_destination_id": "aa0e8400-e29b-41d4-a716-446655440005"
  }
}

If endpoint_id is provided and the attach step fails, the saved destination is still created. The response remains HTTP 201 with data plus an attachment_error object (code + message) at the top level — not inside data. Retry attach from the dashboard or a later API call as needed.

Agent forward destination

Creates a forward destination directly on an endpoint. There is no saved-destination record — agent targets are not reusable templates.

Requires agents.assign_destination on the API key’s role.

curl -s -X POST \
  "https://api.hookdeploy.dev/v1/destinations" \
  -H "Authorization: Bearer hd_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local API",
    "destination_type": "agent",
    "endpoint_id": "550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "660e8400-e29b-41d4-a716-446655440001",
    "target_port": 3000,
    "target_path": "/webhooks/hookdeploy"
  }'

Body fields (agent):

Field	Required	Description
`name`	yes	Display name
`destination_type`	yes	Must be `"agent"`
`endpoint_id`	yes	Endpoint to attach the forward destination to
`agent_id`	yes	UUID of an enrolled agent in your organization
`target_port`	yes	Integer 1–65535 (loopback port on the agent machine)
`target_path`	yes	Path starting with `/` (e.g. `/webhooks/hookdeploy`)
`environment_override`	no	`"development"` only — optional downgrade for this destination

Do not send url, visibility, or is_reusable for agent creates — saved-destination fields do not apply.

Success (201) — forward destination shape:

{
  "data": {
    "id": "aa0e8400-e29b-41d4-a716-446655440005",
    "name": "Local API",
    "destination_type": "agent",
    "agent_id": "660e8400-e29b-41d4-a716-446655440001",
    "target_port": 3000,
    "target_path": "/webhooks/hookdeploy",
    "url": null,
    "enabled": true,
    "created_at": "2026-05-24T12:00:00Z",
    "environment_override": null
  }
}

Agent create errors (returned as top-level error, not attachment_error):

HTTP	Code	When
400	`missing_field`	`endpoint_id`, `agent_id`, `target_port`, or `target_path` absent
400	`bad_request`	Port outside 1–65535, path not starting with `/`, agent not found in your org, invalid `environment_override`, or other validation failure
401	`unauthorized`	Invalid API key
403	`forbidden`	Role lacks `agents.assign_destination` or `endpoints.edit`, endpoint not visible, or RPC permission denied
403	`plan_limit`	Forward destination limit reached for this endpoint (per-plan `max_forward_destinations`)
404	`not_found`	Endpoint not found or not visible to this API key

Production agent enrollment limits (max_agents) are enforced when enrolling or marking agents production — not when assigning an existing agent to a destination. This endpoint does not return agent-count usage.

List saved destinations

GET /v1/destinations

Returns HTTPS saved destinations only. Agent forward destinations never appear here.

curl -s "https://api.hookdeploy.dev/v1/destinations?limit=25" \
  -H "Authorization: Bearer hd_live_YOUR_KEY"

Query parameters: limit (default 25, max 100), before (cursor).

Response:

{
  "data": {
    "data": [
      {
        "id": "990e8400-e29b-41d4-a716-446655440004",
        "name": "Production Webhook",
        "url": "https://myserver.com/webhooks",
        "visibility": "private",
        "is_reusable": true,
        "endpoint_count": 2,
        "created_at": "2026-05-24T12:00:00Z"
      }
    ],
    "meta": {
      "count": 1,
      "has_more": false,
      "next_cursor": null
    }
  }
}

Get saved destination

GET /v1/destinations/:id

Includes a nested endpoints array of linked forward destinations (HTTPS attachments only).

curl -s "https://api.hookdeploy.dev/v1/destinations/DESTINATION_ID" \
  -H "Authorization: Bearer hd_live_YOUR_KEY"

{
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "name": "Production Webhook",
    "url": "https://myserver.com/webhooks",
    "visibility": "private",
    "is_reusable": true,
    "created_at": "2026-05-24T12:00:00Z",
    "endpoints": [
      {
        "endpoint_id": "550e8400-e29b-41d4-a716-446655440000",
        "endpoint_name": "Stripe production",
        "forward_destination_id": "aa0e8400-e29b-41d4-a716-446655440005"
      }
    ]
  }
}

List forward destinations on an endpoint

GET /v1/endpoints/:id/destinations

Returns all forward destinations for an endpoint (HTTPS and agent), ordered by sort_order.

curl -s "https://api.hookdeploy.dev/v1/endpoints/ENDPOINT_ID/destinations" \
  -H "Authorization: Bearer hd_live_YOUR_KEY"

Response:

{
  "data": {
    "data": [
      {
        "id": "990e8400-e29b-41d4-a716-446655440004",
        "name": "Production Server",
        "url": "https://myserver.com/webhooks",
        "enabled": true,
        "method_override": null,
        "created_at": "2026-05-24T12:00:00Z",
        "destination_type": "https",
        "agent_id": null,
        "target_port": null,
        "target_path": null
      },
      {
        "id": "aa0e8400-e29b-41d4-a716-446655440005",
        "name": "Local API",
        "url": null,
        "enabled": true,
        "method_override": null,
        "created_at": "2026-05-24T12:05:00Z",
        "destination_type": "agent",
        "agent_id": "660e8400-e29b-41d4-a716-446655440001",
        "target_port": 3000,
        "target_path": "/webhooks/hookdeploy"
      }
    ]
  }
}

Forward destination fields:

Field	Description
`id`	UUID of the forward destination
`name`	Display name
`destination_type`	`"https"` or `"agent"`
`url`	HTTPS target URL, or `null` for agent destinations
`agent_id`	Enrolled agent UUID for agent destinations, otherwise `null`
`target_port`	Loopback port (1–65535) for agent destinations, otherwise `null`
`target_path`	Loopback path for agent destinations, otherwise `null`
`enabled`	Whether this destination is active. Disabled destinations are skipped during forwarding.
`method_override`	HTTP method to use when forwarding, or `null` to mirror the original request method
`created_at`	ISO 8601 creation timestamp

Retry: Per-destination retry schedules (retry_enabled, retry_schedule, intelligent_retry) apply to HTTPS forward destinations only. Agent destinations use environment-based retry semantics instead — production agents automatically retry retryable failures; development agents never retry, regardless of those flags.

Rate limiting: When rate_limit_enabled is set, both HTTPS and agent forward destinations use the same smooth-delivery queue — requests are scheduled and dispatched at the configured rate.

Forward destinations are managed in the dashboard under Endpoints → [endpoint name] → Destinations. Saved HTTPS destinations live under Destinations.

Error responses (HTTPS saved flow)

HTTP	Code	Cause
400	`bad_request`	Missing `name`/`url` or other validation errors
401	`unauthorized`	Invalid API key
403	`forbidden`	API key lacks permission to manage destinations
403	`plan_limit`	Plan caps (e.g. forward destination limit on attach)
404	`not_found`	Destination or endpoint not found

Next steps

Requests API — Retrieve captured requests and their forwarding results
Endpoints API — Manage endpoint URLs
Private delivery — Enroll agents and route to private infrastructure
Incidents — Correlated forward-failure triage