---
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.25.0
author: Jeremy Longshore <jeremy@intentsolutions.io>
license: MIT
tags:
  - api
  - webhooks
  - emitting-api
compatibility: Designed for Claude Code
title: emitting-api-events
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/emitting-api-events
last_updated: 2026-10-23T05:08:30.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/errors.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/emitting-api-events/references/errors.md), [references/examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/emitting-api-events/references/examples.md), [references/implementation.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/emitting-api-events/references/implementation.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/emitting-api-events`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/emitting-api-events`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/emitting-api-events) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/emitting-api-events`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/emitting-api-events --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/emitting-api-events --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# 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

1. 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`).
2. 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).
3. 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.
4. 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.
5. 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.
6. 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.
7. Create a dead-letter queue for events that exhaust all delivery retry attempts, with alerting and manual replay capability.
8. Write integration tests covering event emission, webhook delivery with signature verification, SSE stream connection with reconnection, and dead-letter queue behavior.

See [`references/implementation.md`](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/emitting-api-events/references/implementation.md) for the full implementation guide.

## Output

- `${CLAUDE_SKILL_DIR}/src/events/emitter.js` - Event emission service with outbox pattern
- `${CLAUDE_SKILL_DIR}/src/events/schemas/` - Versioned event type schema definitions
- `${CLAUDE_SKILL_DIR}/src/events/webhooks/` - Webhook delivery, signing, and retry logic
- `${CLAUDE_SKILL_DIR}/src/events/sse.js` - Server-Sent Events streaming endpoint
- `${CLAUDE_SKILL_DIR}/src/routes/webhooks.js` - Webhook subscription management API
- `${CLAUDE_SKILL_DIR}/src/events/dead-letter.js` - Dead-letter queue handler with replay
- `${CLAUDE_SKILL_DIR}/tests/events/` - Event emission and delivery integration tests

## Error Handling

| Error | Cause | Solution |
|-------|-------|----------|
| Event lost on crash | Application crashes between database commit and event publish | Use transactional outbox pattern: write event to outbox table in same transaction, poll and publish separately |
| Webhook delivery failure | Subscriber endpoint unreachable or returns non-2xx | Retry with exponential backoff; deactivate subscription after 5 consecutive failures; notify subscriber admin |
| Event ordering violation | Concurrent mutations publish events out of order | Use partition keys (resource ID) for ordered delivery within a partition; accept out-of-order across partitions |
| SSE connection memory leak | Server accumulates stale SSE connections without cleanup | Implement heartbeat comments (`:keepalive\n\n`) every 15 seconds; detect and close dead connections |
| Schema version mismatch | Consumer expects v1 event format but receives v2 | Include `version` field in event envelope; support simultaneous v1/v2 delivery; deprecate old versions with notice |

Refer to [`references/errors.md`](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/emitting-api-events/references/errors.md) for comprehensive error patterns.

## Examples

**Order lifecycle events**: Emit `order.created`, `order.payment_received`, `order.shipped`, and `order.delivered` events with order details, enabling downstream services (warehouse, email, analytics) to react asynchronously.

**SSE live notifications**: Browser client connects to `GET /events/stream?types=message.received,order.updated` and receives real-time event updates with automatic reconnection and `Last-Event-ID` replay on network interruption.

**Transactional outbox**: Write the event record to an `outbox` table within the same database transaction as the API mutation, then poll the outbox table every 100ms to publish events to Kafka, ensuring at-least-once delivery.

See [`references/examples.md`](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/emitting-api-events/references/examples.md) for additional examples.

## Resources

- CloudEvents specification: https://cloudevents.io/
- Server-Sent Events (MDN): https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events
- Transactional outbox pattern: Microservices.io
- Webhook best practices: Standard Webhooks specification
