# API Webhooks Event Driven

> Design outbound webhooks and event-driven API delivery: retry schedules, 2xx-only success, idempotent receivers, and dual notify with polling. Use when adding webhook APIs or reviewing delivery reliability.

- Skill: `deangrant/api-webhooks-event-driven` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add deangrant/api-webhooks-event-driven`
- Raw SKILL.md: https://api.skillmd.com/api/skills/deangrant/api-webhooks-event-driven/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: deangrant (https://skillmd.com/u/deangrant)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/deangrant/api-webhooks-event-driven

---


# Webhooks and Event-Driven API Design

Use this skill when the API **pushes events** to customer endpoints.

---

## 1. Delivery

POST event payloads to customer URLs. Treat only **2xx** as success. Retry with
exponential backoff (+ jitter) on failure; cap attempts; dead-letter afterward.

---

## 2. Receiver expectations

Receivers must be **idempotent** (delivery at-least-once). Provide event `id`
for dedupe. Sign payloads (see webhook signature skill). Offer polling/API
fetch as fallback.

---

## 3. Quick checklist

- [ ] Documented retry schedule.
- [ ] 2xx-only success.
- [ ] Event IDs for idempotent consumers.
- [ ] Signatures + timestamp window.
- [ ] Manual replay / delivery logs.

See [reference.md](reference.md) and [examples.md](examples.md).