Back to Home

CoffeeRelay Documentation

Webhook relay built for AI agents and event-driven workflows

Quick Links

For AI Agents — Setup Guide

Current Status: API keys are not yet available. Endpoint and destination management currently requires dashboard access via GitHub OAuth.

Coming in Phase 1: Bearer token auth, OpenAPI spec, TypeScript SDK, and official MCP server.

What Works for Agents Today

✅ Public Ingest

POST to /api/in/{slug} — no auth required

✅ Signature Verification

Every forwarded webhook includes x-coffeerelay-signature

✅ Session State

Webhooks with x-session-id get state hydrated

✅ Idempotency

Send idempotency-key header for deduplication

Setup Steps (Current Manual Process)

  1. Human creates account and endpoint
    • Sign up at /sign-in (GitHub OAuth)
    • Dashboard → Endpoints → New Endpoint
    • Copy slug and signing secret
  2. Human adds destination(s)
    • Endpoint detail page → Destinations tab
    • Add destination URL where agent receives webhooks
    • Copy ingest URL: https://coffeerelay.dev/api/in/{slug}
  3. Register ingest URL with external service
    • Paste ingest URL into Stripe/GitHub/etc webhook settings
    • External service will POST events to CoffeeRelay
    • CoffeeRelay forwards to your destination(s) in real-time
  4. Agent verifies signatures
    • Check x-coffeerelay-signature header on received webhooks
    • Use signing secret from dashboard to verify HMAC-SHA256
    • See llms-full.txt for code examples

Test Your Setup

curl -X POST https://coffeerelay.dev/api/in/your-slug \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": "hello"}'

Expected response:

{
  "received": true,
  "logId": "clx...",
  "destinations": 2
}

Core Features

Multi-Destination Fan-Out

One webhook in → multiple destinations receive it instantly in parallel

Session State Storage

Persist agent context across webhook events for multi-step workflows

Circuit Breaker

Auto-pause on error spikes to prevent expensive agent retry loops

Dead Letter Queue

Capture failed deliveries for bulk replay after incidents (Pro)

Idempotency Keys

Deduplicate webhooks to prevent expensive duplicate LLM calls

Policy Rules

Claude Code safety with allow/deny patterns for agent tool use

Plans & Pricing

Free

$0

  • 1 endpoint
  • 1 destination
  • 1K requests/month
  • 1-day log retention

Starter

$10/mo

  • 5 endpoints
  • 3 destinations each
  • 10K requests/month
  • 7-day logs
  • Replay + circuit breaker
  • 50 sessions/endpoint

Pro

$25/mo

  • 25 endpoints
  • 10 destinations each
  • 100K requests/month
  • 30-day logs
  • DLQ + unlimited rules
  • 500 sessions/endpoint

Why Event-Driven for AI Agents?

  • Saves tokens and compute — Agents only activate when real events arrive, no empty polling requests
  • Near real-time reactions — Respond instantly to payments, code pushes, support tickets
  • Lower API costs — 1 request per event vs N polling requests
  • Simpler architecture — No cron jobs, timers, or polling loops to manage

Need Help?

Email: support@coffeerelay.dev

Complete Docs: llms-full.txt