API reference

Manage your webhooks programmatically. Base URL: https://cardano.delivery/api. All requests and responses are JSON. For event payloads, signatures and condition semantics see the main documentation.

Authentication

Create an API key in the dashboard (API keys section - shown once at creation). Send it as a bearer token:

curl https://cardano.delivery/api/webhooks \
  -H "Authorization: Bearer cdk_your_api_key"

Keys act with the full permissions of your account, except that they cannot create or revoke other API keys (that requires a dashboard session). Up to 5 keys per account.

The webhook object

{
  "id": "b592db93-4bb9-4bd0-a196-9dd9c09577fa",
  "name": "my webhook",
  "description": null,
  "status": "enabled",          // enabled | disabled
  "target_url": "https://example.com/hook",
  "type": "transaction",        // see trigger types in the docs
  "confirmations": 1,            // 1–10; ignored for detection types
  "auth_token": "…",            // HMAC secret for Delivery-Signature
  "created_at": "2026-08-04T09:00:00.000Z",
  "updated_at": null,
  "conditions": [
    { "id": "…", "type": "recipient", "operator": "=", "value": "addr1…", "selector": null }
  ]
}

GET/webhooks

Returns all of your webhooks, newest first.

curl https://cardano.delivery/api/webhooks \
  -H "Authorization: Bearer $KEY"

POST/webhooks

Creates a webhook. Returns the full webhook object (201), including the generated auth_token.

curl -X POST https://cardano.delivery/api/webhooks \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pool retirement alert",
    "type": "pool",
    "target_url": "https://example.com/hook",
    "confirmations": 2,
    "conditions": [
      { "type": "poolId", "operator": "=", "value": "pool1…" },
      { "type": "action", "operator": "=", "value": "retire" }
    ]
  }'

GETPATCHDELETE/webhooks/{id}

GET returns one webhook. PATCH replaces its definition - send the same body as create, plus optional "status": "enabled" | "disabled"; conditions are replaced wholesale. DELETE removes the webhook and its delivery history (204); deliveries stop within ~10 seconds.

POST/webhooks/{id}/token

Rotates the HMAC secret. Returns {"auth_token": "…"}. Existing signature verification breaks until your consumer uses the new secret.

GET/webhooks/{id}/history?limit=50

Recent delivery attempts, newest first (limit ≤ 100):

[
  {
    "id": "…",
    "success": true,
    "target_url": "https://example.com/hook",
    "fired_at": "2026-08-04T09:41:12.000Z",
    "status_code": 200,
    "error_message": null,
    "payload": "…",      // delivered JSON body (truncated)
    "response": "…"      // your endpoint's response (truncated)
  }
]

Errors & limits

Errors return a JSON body {"error": "human readable message"}:

POST/ephemeral - no account needed

Temporary webhooks for agents and quick scripts: one unauthenticated request creates a webhook that expires by itself (default 1 hour, max 24). Omit target_url for inbox mode: matched events are stored and you poll them, so you need no public endpoint at all. Machine-readable summary at /llms.txt.

curl -X POST https://cardano.delivery/api/ephemeral \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transaction",
    "ttl_seconds": 3600,
    "conditions": [
      { "type": "recipient", "operator": "=", "value": "addr1..." }
    ]
  }'

# 201 -> { "id", "manage_token": "eph_...", "events_url", "expires_at", ... }

Everything after creation is scoped by the returned manage_token (shown once):

curl https://cardano.delivery/api/ephemeral/{id}/events \
  -H "Authorization: Bearer eph_your_manage_token"

With a target_url, deliveries are signed exactly like permanent webhooks. Limits: 5 creates per hour per IP, 5 conditions, TTL 60s to 24h. For anything permanent, create a free account.

MCP server

The same ephemeral capability is exposed as a remote MCP server, so MCP-capable agents (Claude, Cursor, and friends) can subscribe to Cardano events mid-task. Endpoint: https://cardano.delivery/mcp (Streamable HTTP, no auth).

Claude Code:

claude mcp add --transport http cardano-delivery https://cardano.delivery/mcp

Or in any client's MCP config JSON:

{
  "mcpServers": {
    "cardano-delivery": { "url": "https://cardano.delivery/mcp" }
  }
}

Tools: create_webhook, poll_events, get_webhook_status, deactivate_webhook. Same limits as the ephemeral REST API.