| name | emitting-api-events |
| description | Build event-driven APIs with webhooks, Server-Sent Events, and real-time notifications.
Use when building event-driven API architectures.
Trigger with phrases like "add webhooks", "implement events", or "create event-driven API".
|
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash(api:events-*) |
| version | 1.24.0 |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| license | MIT |
| tags | ["api","webhooks","emitting-api"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
Emitting API Events
Overview
Build event-driven API architectures using outbound webhooks, Server-Sent Events (SSE), and message broker integration. Implement event emission from API mutations, event schema registry, subscriber management, delivery guarantees with retry logic, and event sourcing patterns for maintaining a complete audit log of API state changes.
Prerequisites
- Message broker: Redis Pub/Sub, RabbitMQ, Apache Kafka, or AWS SNS/SQS
- Persistent storage for event log and subscriber registrations (PostgreSQL, MongoDB)
- Webhook delivery infrastructure with retry queue (Bull, Celery, or managed service)
- Event schema registry for versioned event type definitions
- SSE-capable web framework for real-time event streaming to browser clients
Instructions
- Identify event-producing operations using Grep and Read, cataloging every API mutation (POST, PUT, PATCH, DELETE) that should emit events, with event type names following
resource.action convention (e.g., order.created, user.updated).
- Define event schemas for each event type with versioning: include
eventId (UUID), eventType, version, timestamp (ISO 8601), source (service identifier), and data (type-specific payload).
- Implement the event emitter service that publishes events to the message broker after successful API mutations, using the transactional outbox pattern to ensure events are not lost on application crash.
- Build a webhook subscription management API:
POST /webhooks (subscribe), GET /webhooks (list), DELETE /webhooks/:id (unsubscribe), with URL validation, event type filtering, and signing secret generation.
- Implement webhook delivery with HMAC-SHA256 signed payloads, configurable retry policy (exponential backoff: 1min, 5min, 30min, 2hr, 24hr), and automatic subscription deactivation after consecutive failures.
- Add Server-Sent Events endpoint (
GET /events/stream) for real-time event delivery to browser clients, with Last-Event-ID support for reconnection and missed event replay.
- Create a dead-letter queue for events that exhaust all delivery retry attempts, with alerting and manual replay capability.
- Write integration tests covering event emission, webhook delivery with signature verification, SSE stream connection with reconnection, and dead-letter queue behavior.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
