> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lithoblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage destinations with the API

> Create destinations, preserve secret headers, and interpret signed test results.

See [availability](/guides/availability) for production and staging endpoints.

## Manage destinations

The `/v1/destinations` API supports list, get, create, patch and delete. Reads require
`destinations:read`; writes require `destinations:write` (admin or owner). Credentials go in
`headers`; `auth_type` describes the authentication style and does not synthesize an Authorization
header. URLs are readable by organization members: keep secrets in headers, not URL query strings.

```json theme={null}
{
  "name": "Approval receiver",
  "url": "https://your-receiver.example/approval",
  "method": "POST",
  "auth_type": "bearer",
  "headers": { "Authorization": "Bearer YOUR_RECEIVER_TOKEN" },
  "timeout_ms": 10000,
  "retry_enabled": false
}
```

POST this body to `/v1/destinations` with a unique `Idempotency-Key`. All responses replace header
values with `•••`. A PATCH omitting `headers` preserves credentials; a supplied object replaces the
entire header set, and `{}` clears it. Sending masked values back is rejected. Unknown fields,
invalid enums and numeric limits produce `422 validation_failed`, before database writes. Invalid
compiled modal content returns 400. Bodies over 256 KiB are rejected with 413.

DELETE returns 409 while a **current template version** references the destination, including a
modal submission webhook configured on a button. Old sent messages and draft/historical versions
are not protected by that check: deleting their destination makes subsequent clicks fail. Historical
interaction logs remain, with the deleted destination ID set to null. To stop dispatch deliberately,
PATCH `is_active: false`. Existing runtime dispatch already checks active status.

### Signed destination tests

`POST /v1/destinations/{id}/test` accepts `{ "signing_secret": "YOUR_SHARED_TEST_SECRET" }` and an
optional `Idempotency-Key`. This dispatches one real request using the destination's method and
stored headers, with a generated `lithoblocks.destination_test` payload. It does not spend a message
credit or retry automatically. The receiver's HTTP status and elapsed milliseconds are returned;
its response body is discarded. A completed non-2xx response returns `delivered: false` with that
status. A transport failure, timeout or blocked redirect returns HTTP 502: delivery is uncertain,
and an idempotency key retains that outcome for reconciliation.

Tests are available only for HTTPS receiver hosts enabled for your environment. IP addresses, alternate ports, URL credentials, and redirects are not allowed. If your receiver is not enabled, contact support. A destination test sends a real request; use an endpoint you control.

The receiver verifies `X-Lithoblocks-Signature: v1=<hex>` as HMAC-SHA256 over
`v1:<X-Lithoblocks-Timestamp>:<raw request body>`, using the supplied test secret. Compare signatures
in constant time and reject stale timestamps/reused test IDs. The test secret is never stored or
returned. This test signature does **not** change the existing authentication protocol for ordinary
button or submission delivery; those continue to use configured headers.

See [Webhook destinations](/guides/webhook-destinations) for UI setup and [payload variables](/guides/webhook-variables) for action payloads.