# CoffeeRelay

> CoffeeRelay is a webhook relay service built for AI agents. It provides a single, stable ingest URL that receives webhooks from external systems and fans them out in real-time to multiple destination URLs, enabling event-driven workflows instead of polling.

Website: https://coffeerelay.dev
Full Docs: https://coffeerelay.dev/llms-full.txt

## Core Capabilities

- Single ingest URL with multi-destination fan-out (parallel delivery)
- HMAC-SHA256 signature verification via `x-coffeerelay-signature` header
- Webhook replay for failed deliveries (Starter/Pro plans)
- Dead Letter Queue for incident recovery (Pro plan)
- Circuit breaker with auto-pause on error spikes (Starter/Pro plans)
- Idempotency key deduplication (Starter/Pro plans)
- AI Agent session state storage for stateful workflows (Starter/Pro plans)
- Policy rules for Claude Code agent safety (Starter/Pro plans)
- Email alerts on delivery failures (Starter/Pro plans)
- Real-time delivery logs with status, latency, response bodies
- **API keys for programmatic access** (All plans)

## For AI Agents — Quick Setup

**New:** API keys now available for programmatic access!

### Setup with API Keys (Recommended)

1. **Create API Key** — Sign in at https://coffeerelay.dev/dashboard/settings and create an API key
2. **Bootstrap Endpoint** — One API call creates endpoint + destination:

```bash
curl -X POST https://coffeerelay.dev/api/agent/bootstrap \
  -H "Authorization: Bearer cr_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"destinationUrl": "https://your-agent.com/webhook"}'
```

Response:
```json
{
  "ingestUrl": "https://coffeerelay.dev/api/in/abc123",
  "endpoint": { "id": "...", "slug": "abc123", "signingSecret": "whsec_..." },
  "destination": { "id": "...", "url": "https://your-agent.com/webhook" }
}
```

3. **Register ingest URL** — Use the returned `ingestUrl` in Stripe/GitHub/etc
4. **Verify signatures** — Use the `signingSecret` to verify incoming webhooks

### Manual Setup (Alternative)

1. Sign up at https://coffeerelay.dev/sign-in (GitHub OAuth)
2. Create endpoint and destination(s) in dashboard
3. Copy ingest URL and signing secret
4. Agent uses ingest URL to receive webhooks

## API Authentication

**API Keys:** Bearer token format `Authorization: Bearer cr_live_xxx...`

**Plan Limits:**
- Free: 1 API key
- Starter: 3 API keys
- Pro: 10 API keys

## Management API (with API Keys)

### Bootstrap (Create Endpoint + Destination)

**POST** `https://coffeerelay.dev/api/agent/bootstrap`

Headers:
```
Authorization: Bearer cr_live_xxx...
Content-Type: application/json
```

Body:
```json
{
  "destinationUrl": "https://your-app.com/webhook",
  "name": "My Endpoint" // optional
}
```

### List Endpoints

**GET** `https://coffeerelay.dev/api/endpoints`

### Create Endpoint

**POST** `https://coffeerelay.dev/api/endpoints`

Body: `{"name": "My Endpoint"}`

### Add Destination

**POST** `https://coffeerelay.dev/api/endpoints/{id}/destinations`

Body: `{"url": "https://your-app.com/webhook"}`

### Get Logs

**GET** `https://coffeerelay.dev/api/logs/{endpointId}?limit=50`

## Ingest API (Public)

**POST | PUT | PATCH | DELETE** `https://coffeerelay.dev/api/in/{slug}`

Send webhooks to this URL. CoffeeRelay forwards to all active destinations.

**No authentication required** — this is the public endpoint you give to Stripe, GitHub, etc.

**Request:** Any headers and body. Forwarded as-is (minus hop-by-hop headers).

**Response:**
```json
{
  "received": true,
  "logId": "clx...",
  "destinations": 2
}
```

**Special Headers (Optional):**

- `idempotency-key` or `x-idempotency-key`: Deduplicate webhooks (Starter/Pro)
- `x-session-id` or body `session_id`: Load agent session state (Starter/Pro)

**Signature Verification:**

Every forwarded webhook includes:
```
x-coffeerelay-signature: t=1234567890,v1=abc123...
```

Verify using HMAC-SHA256 of `{timestamp}.{raw_body}` with your endpoint's signing secret.

## AI Agent Features

### Session State (Starter/Pro)

For multi-step workflows, CoffeeRelay stores agent state between webhook events:

- Send webhooks with `x-session-id` header or `session_id` in JSON body
- State is automatically hydrated in forwarded webhooks via headers:
  - `x-session-id`
  - `x-session-state` (JSON)
  - `x-correlation-id`
  - `x-session-metadata` (JSON)

### Circuit Breaker (Starter/Pro)

When error rate exceeds threshold, endpoint auto-pauses to prevent expensive retry storms.

### Dead Letter Queue (Pro)

Failed deliveries are captured for bulk replay after incidents.

### Idempotency (Starter/Pro)

Duplicate webhooks (same `idempotency-key`) within 24h return cached response.

### Policy Rules (Starter/Pro)

Claude Code HTTP hooks integration with policy enforcement:
- Block destructive commands
- Read-only mode for agents
- Custom allow/deny patterns

## Plans

- **Free**: 1 endpoint, 1 destination, 1K requests/month, 1-day logs, 1 API key
- **Starter ($10/mo)**: 5 endpoints, 3 destinations/endpoint, 10K requests/month, 7-day logs, replay, circuit breaker, idempotency, 50 sessions/endpoint, 3 API keys
- **Pro ($25/mo)**: 25 endpoints, 10 destinations/endpoint, 100K requests/month, 30-day logs, DLQ, 500 sessions/endpoint, 10 API keys

## Links

- [Public Documentation](https://coffeerelay.dev/docs): Ungated setup guide for AI agents
- [Sign Up](https://coffeerelay.dev/sign-in): Create account (GitHub OAuth)
- [Dashboard](https://coffeerelay.dev/dashboard): Manage endpoints and destinations
- [Full Documentation](https://coffeerelay.dev/llms-full.txt): Complete API reference