Integrations with external systems must be idempotent, observable, and version-safe.
Webhooks
Verify signatures before processing
Use idempotency keys to deduplicate deliveries
Return quickly; enqueue heavy work
Log correlation IDs, not full payloads
Retries
Exponential backoff with jitter
Cap retry attempts; route poison messages to a dead-letter queue
Make handlers safe to run twice
Protocol versioning
Version message schemas explicitly (v1, v2)
Support backward-compatible reads during migrations
Never break consumers without a deprecation window
Testing
Contract tests against recorded fixtures
Simulate timeout and duplicate delivery in integration tests
Raw content
Copy into your project — e.g. .instructions.md, .agent.md, or SKILL.md
## Overview
Integrations with external systems must be idempotent, observable, and version-safe.
## Webhooks
- Verify signatures before processing
- Use idempotency keys to deduplicate deliveries
- Return quickly; enqueue heavy work
- Log correlation IDs, not full payloads
## Retries
- Exponential backoff with jitter
- Cap retry attempts; route poison messages to a dead-letter queue
- Make handlers safe to run twice
## Protocol versioning
- Version message schemas explicitly (v1, v2)
- Support backward-compatible reads during migrations
- Never break consumers without a deprecation window
## Testing
- Contract tests against recorded fixtures
- Simulate timeout and duplicate delivery in integration tests