AGENTS.md Template for Webhook Delivery Architecture

Overview

This AGENTS.md template defines the operating model for a webhook delivery architecture using AI coding agents. It specifies roles, constraints, and collaboration rules to support both single agent workflows and multi agent orchestration across receipt, validation, delivery, and failure handling.

Direct answer style summary: This AGENTS.md template standardizes webhook delivery workflows, agent handoffs, tool governance, and human review to ensure reliable, auditable delivery of webhook payloads.

When to Use This AGENTS.md Template

When building a webhook receiver and dispatcher that must scale across multiple endpoints
When you need clear handoff rules between planner, implementer, tester, and domain experts
When robust retries, idempotency, and dead letter handling are required
When governance, security, and production readiness are required

Copyable AGENTS.md Template

# AGENTS.md
Project Role
  Webhook Delivery Platform Engineer responsible for end to end reliability of webhook delivery

Agent roster and responsibilities
  ReceiverAgent
    - Verify signature of inbound webhook
    - Parse and normalize payload
    - Forward to ValidationAgent
  ValidationAgent
    - Validate required fields event_id event_type payload timestamp
    - Reject invalid payload with structured error and route to DLQ
  EnrichmentAgent
    - Attach delivery metadata like id timestamp and idempotency key
    - Enrich with domain metadata if available
  QueueEnqueueAgent
    - Enqueue message to delivery queue with idempotency key
  DeliveryAgent
    - POST payload to target endpoint
    - Apply backpressure and respect timeouts
  RetryManagerAgent
    - Manage exponential backoff and max retries
    - Move failed messages to Dead Letter if max retries exceeded
  DomainSpecialistAgent
    - Provide domain specific payload enrichment or validation when required
  AuditAgent
    - Persist event trail for observability
  OrchestratorAgent
    - Coordinate handoffs between agents, enforce timeouts, trigger retries and escalation
  HumanReviewAgent
    - Escalate complex or high risk events to humans when needed

Supervisor or orchestrator behavior
  OrchestratorAgent monitors each webhook flow, enforces timeouts, and triggers retries or dead letter routing as needed
  It ensures that handoffs follow the defined sequence receiver -> validation -> enrichment -> queue -> delivery
  It coordinates multi agent collaboration and ensures idempotent effects

Handoff rules between agents
  ReceiverAgent -> ValidationAgent
  ValidationAgent -> EnrichmentAgent
  EnrichmentAgent -> QueueEnqueueAgent
  QueueEnqueueAgent -> DeliveryAgent
  DeliveryAgent -> AuditAgent
  On failure, handoff to RetryManagerAgent or HumanReviewAgent
  In multi agent flows, DomainSpecialistAgent can intervene before DeliveryAgent if domain rules require

Context memory and source of truth rules
  Use a persistent event store as source of truth
  Pass context via structured messages; avoid hidden state
  Do not rely on ephemeral memory across events

Tool access and permission rules
  Agents may call outbound HTTP to whitelisted endpoints only
  Secrets must be retrieved from a secure vault and never logged
  Production systems require approval gates

Architecture rules
  Event driven architecture with idempotent processing
  Use unique delivery ids and idempotency keys to avoid duplicate deliveries
  All outputs must be deterministic given the same input
  Separate concerns between receipt, validation, enrichment, delivery, and auditing

File structure rules
  Place all webhook delivery related code under webhook-delivery
  Do not mix with unrelated services

Data API and integration rules
  Validate signature using shared secret
  Support HS256 style signature and expose clear error on verification failure

Validation rules
  event_id and event_type required
  payload must be non empty
  timestamp must be present

Security rules
  Validate all webhook signatures
  Rotate signing keys regularly
  Do not log sensitive fields

Testing rules
  Unit tests for each agent
  Integration tests simulating webhook flows
  End to end tests with replayable fixtures
  Regression tests for delivery failures

Deployment rules
  Canary rollout and gradual traffic increase
  Monitor delivery success rate and latency
  Rollback plan for failed deployments

Human review and escalation rules
  Route high risk events to on call engineer with context
  Provide a concise summary and logs to human reviewers

Failure handling and rollback rules
  On failure revert to last good state
  Rollback any partial side effects
  Notify stakeholders on critical failures

Things Agents must not do
  Do not bypass validation or source of truth
  Do not modify production data without approval
  Do not perform unsanctioned outbound requests

Recommended Agent Operating Model

The recommended agent operating model assigns clear roles for receipt, validation, enrichment, delivery, and orchestration. The planner or orchestrator controls sequence and timing, while implementers perform the actual delivery actions. Reviewers provide governance for risky events, and domain specialists step in when payload semantics require domain knowledge. Handoffs are explicit and traceable, and all decisions are grounded in a single source of truth.

Recommended Project Structure

webhook-delivery
  agents
    receiver
    validator
    enricher
    queue
    deliver
    retry
    idempotency
    audit
  orchestrator
  config
  tests
  docs

Core Operating Principles

Single source of truth for every webhook event
Idempotent processing and deterministic outputs
Explicit, auditable agent handoffs
Strong observability and traceability
Security by default and least privilege
Clear ownership and escalation paths

Agent Handoff and Collaboration Rules

Planner orchestrates sequence and timing; no step bypass.
Implementers own delivery actions and respect timeouts.
Reviewers validate risk, approve human escalation when needed.
Testers verify integration points and end to end reliability.
Researchers Domain Specialist agents provide domain context when needed.
Handoffs are deterministic and time-bounded.

Tool Governance and Permission Rules

All outbound requests go to whitelisted endpoints only
Secrets retrieved from a vault; never logged or stored in plain text
Secrets rotated on a defined cadence; access audited
Production changes require approval gates and observable rollback paths

Code Construction Rules

Write idempotent, dead-letter capable code paths
Validate inputs at the earliest stage
Keep the agent surface area small and well defined
Avoid hard coded endpoints; configure via environment or config service
Document all non trivial decisions in the AGENTS.md template

Security and Production Rules

Verify inbound webhook signatures before processing
Rotate keys and secrets regularly; enforce secure transmission
Limit blast radius: agent level permissions and network egress controls
Implement monitoring and alerting for outages and anomalies

Testing Checklist

Unit tests for each agent function
Integration tests covering signature validation, enrichment, queueing, and delivery
End to end tests with sample webhook payloads
Smoke tests after deployment to catch regressions

Common Mistakes to Avoid

Skipping signature verification or proper authentication
Assuming delivery is perfect without idempotency and retries
Overlapping responsibilities that blur ownership
Ignoring dead-letter and escalation paths

FAQ

What is this AGENTS.md Template for webhook delivery architecture?

It is a copyable AGENTS.md template that standardizes roles, handoffs, and governance for a webhook delivery workflow using AI coding agents.

How do agents coordinate delivery across receipt validation and retry?

The orchestrator enforces a fixed sequence receiver validation enrichment queue delivery with a retry policy that escalates to human review if needed.

What are the handoff rules between planner implementer reviewer tester and domain specialist?

Handoffs are explicit: planner to implementer for delivery actions, reviewer for risk checks, tester for validation, domain specialist for domain specific enrichment, with a fallback to the orchestrator for retries and escalation.

How is idempotency enforced and how are secrets managed?

Idempotency keys are attached to each webhook delivery and checked against a durable store; secrets live in a vault and are never logged or embedded in code.

What should agents not do and how are failures handled?

Do not bypass validations, modify the source of truth, or access production systems without approval. Failures trigger retries, dead-letter handling, or human escalation with full context.

Target User

Use Cases