playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / emitting-api-events

emitting-api-events skill

/plugins/api-development/api-event-emitter/skills/emitting-api-events

This skill helps you implement event-driven APIs by generating boilerplate, wiring webhooks and real-time notifications with robust validation.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill emitting-api-events

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.4 KB
---
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.0.0
author: Jeremy Longshore <[email protected]>
license: MIT
---

# Emitting Api Events

## Overview


This skill provides automated assistance for api event emitter tasks.
This skill provides automated assistance for the described functionality.

## Prerequisites

Before using this skill, ensure you have:
- API design specifications or requirements documented
- Development environment with necessary frameworks installed
- Database or backend services accessible for integration
- Authentication and authorization strategies defined
- Testing tools and environments configured

## Instructions

1. Use Read tool to examine existing API specifications from {baseDir}/api-specs/
2. Define resource models, endpoints, and HTTP methods
3. Document request/response schemas and data types
4. Identify authentication and authorization requirements
5. Plan error handling and validation strategies
1. Generate boilerplate code using Bash(api:events-*) with framework scaffolding
2. Implement endpoint handlers with business logic
3. Add input validation and schema enforcement
4. Integrate authentication and authorization middleware
5. Configure database connections and ORM models
1. Write integration tests covering all endpoints


See `{baseDir}/references/implementation.md` for detailed implementation guide.

## Output

- `{baseDir}/src/routes/` - Endpoint route definitions
- `{baseDir}/src/controllers/` - Business logic handlers
- `{baseDir}/src/models/` - Data models and schemas
- `{baseDir}/src/middleware/` - Authentication, validation, logging
- `{baseDir}/src/config/` - Configuration and environment variables
- OpenAPI 3.0 specification with complete endpoint definitions

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources

- Express.js and Fastify for Node.js APIs
- Flask and FastAPI for Python APIs
- Spring Boot for Java APIs
- Gin and Echo for Go APIs
- OpenAPI Specification 3.0+ for API documentation

Overview

This skill helps you build event-driven APIs that emit notifications via webhooks, Server-Sent Events (SSE), and real-time channels. It provides scaffolding, endpoint design patterns, and integration guidance so you can quickly add event emission to existing APIs. The goal is reliable, secure delivery of events and clear documentation for consumers.

How this skill works

The skill inspects API design specs, defines resource models and event contracts, and generates endpoint scaffolding for emitters and delivery middleware. It adds handlers for producing events, configures transport mechanisms (HTTP webhooks, SSE streams, or real-time sockets), and wires authentication, retries, and logging. It also produces OpenAPI 3.0 documentation and integration test templates to validate event flows.

When to use it

  • You need to notify external systems or clients about state changes in near real-time
  • You want to add webhooks to an existing REST API without rearchitecting the backend
  • You require server-to-client streaming (SSE) for live feeds or progress updates
  • You need a developer-friendly contract (OpenAPI + event schemas) for third-party integrations
  • You are designing microservices that publish domain events to interested subscribers

Best practices

  • Define clear event contracts (type, schema, required fields) and publish them in OpenAPI or a schema registry
  • Use idempotent event handlers and include delivery identifiers to support retries
  • Protect delivery channels with authentication, signature verification, and rate limits
  • Implement durable delivery: queue events, backoff retries, dead-lettering for failed webhooks
  • Provide observability: delivery logs, metrics (success/failure/latency), and replay/debug endpoints
  • Include integration tests and consumer contract tests to prevent breaking changes

Example use cases

  • User account service emits account.created and account.updated events to third-party CRM via webhooks
  • E-commerce platform streams order status updates to a dashboard using SSE for live order tracking
  • Payment processor publishes transaction.completed events to downstream analytics via queued deliveries
  • Collaboration app pushes real-time notifications to connected clients over WebSocket or SSE when comments are added
  • CI system emits job.progress events so dashboards can render live build logs

FAQ

Which transport should I choose: webhooks, SSE, or real-time sockets?

Choose webhooks for server-to-server notifications, SSE for simple server-to-browser streams, and WebSocket/real-time sockets for bidirectional low-latency use cases.

How do I handle failed deliveries to webhook subscribers?

Queue failed attempts, apply exponential backoff with jitter, mark persistent failures to a dead-letter store, and notify the subscriber with a retry webhook or admin UI.