SKILL.md
Webhook reliability reviewer
An evidence-first workflow to verify signature handling, replay protection, retries, ordering, and idempotent processing.
- Revision
- 2
- Verified
- 2026-10-20
Compatibility and paths
Codex
skills/webhook-reliability/SKILL.mdClaude Code
.claude/skills/webhook-reliability/SKILL.mdVS Code
.github/skills/webhook-reliability/SKILL.mdTrust and provenance
Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.
Generated assetReady to copy or download
---
name: webhook-reliability
description: Reviews webhook authenticity, durable acknowledgement, redelivery, ordering and effect idempotency using raw-byte evidence. Use for a receiver design or missed/duplicate deliveries; distinguish signature validation from replay guarantees without hitting a live endpoint.
license: CC-BY-4.0
compatibility: Reviews redacted contracts and synthetic cases offline. Live API writes, queue execution, webhooks and external side effects need separate scoped authorization.
metadata:
author: oneliners
version: "2.0.0"
---
# Webhook reliability reviewer
## Establish the provider-specific contract
Request provider/version, event/action allowlist, subscription/repository/account mapping, signature algorithm and byte format, delivery IDs, redelivery behavior, response deadline, payload limits and durable consumer boundary. Do not generalize another vendor's signed timestamp or retry contract to GitHub. Obtain only redacted headers/minimal synthetic payloads; never ask for the real signing key or log it. Secret rotation and historical redelivery need an explicit retention/acceptance plan, not an always-accept-old-key workaround.
## Authenticate bytes before interpreting data
Capture bounded original request bytes before a JSON middleware rewrites them. Validate the documented signature format, compare safely and reject failures before any queue/effect writes. Only then parse and validate allowed payload/context. TLS and an IP allowlist are not replacements for signature validation. Header names are case-insensitive at the HTTP layer; header VALUES still require the algorithm's format. The demo below uses lowercase sha256/hex as an explicit primitive contract, not a complete HTTP parser or receiver.
## Worked GitHub-shaped delivery
The minimal body is synthetic, not the full GitHub schema. The key is deliberately public and must never be installed in a real receiver. The signature is generated from these exact bytes using Node's standard crypto library.
```json
{
"provenance": "synthetic minimal payload and public demo key; not a captured GitHub delivery",
"deliveryId": "fixture-delivery-1",
"rawBodyUtf8": "{\"repository\":{\"id\":7},\"pull_request\":{\"id\":42,\"head\":{\"sha\":\"fixture-head-1\"}},\"action\":\"opened\"}",
"signature": "sha256=b32b11578705af5125070e3699299c751dd52718f8919f352f07ed509fc05976",
"practiceKey": "synthetic-practice-key-NOT-A-PRODUCTION-SECRET",
"receiverPolicy": "Validate raw bytes before parse; durable subscription-scoped delivery deduplication; bounded ingress and queue; no expensive synchronous processing; business consumer idempotency required separately."
}
```
## Review and negative-test interpretation
Authenticity primitive: HMAC-SHA256 over the EXACT supplied raw UTF-8 bytes validates against the public practice key/signature. Parsing and pretty-printing the same JSON changes bytes and fails that original signature. Missing, malformed or changed-body signatures must be rejected before queue writes. The practice key is public teaching input, never a usable production secret.
Delivery model: first verified fixture-delivery-1 -> QUEUED_MODEL_ONLY; same ID/same bytes -> DUPLICATE_NO_NEW_WORK; same ID/different correctly signed bytes -> STOP_ID_BODY_CONFLICT. A real receiver needs an atomic durable uniqueness/transaction boundary across all workers and a reviewed retention period. A process-local Map loses state on restart and does not demonstrate that boundary. A2xx response is an ingress acknowledgement after durable acceptance, not proof that downstream processing completed.
Important replay limit: the GitHub HMAC binds the payload body, not every HTTP header or a signed timestamp. A captured valid body/signature replayed with a new X-GitHub-Delivery value can pass this primitive and bypass ID-only deduplication. Do not claim that an unsigned Date header or a five-minute clock check solves this. Bound exposure with TLS, secret protection/rotation policy, durable deduplication, scoped ingress controls and idempotent business effects; document retention and late replay limitations. A payload hash alone is also not always a valid business event key because distinct legitimate events can share content.
Ordering/recovery: check permitted event/action and subscription/repository context before effects. Treat X-GitHub-Event as untrusted routing input and validate the selected payload schema/context. Reconcile stale/out-of-order changes by the domain's authoritative revision/event semantics, not arrival order alone. GitHub redelivery retains the delivery ID; preserve that ID and original receipt evidence when requesting an authorized redelivery. Do not assume the provider automatically retries every failed delivery.
Verification ledger: correct bytes PASS; altered whitespace FAIL under original signature; missing/short header FAIL; duplicate verified ID creates no new modeled work; changed ID demonstrates the replay limitation; restart/concurrency/durable commit/downstream retries remain unverified. No webhook endpoint, secret, provider redelivery or external effect was used.
## Durable ingestion and consumer contract
Bound body size and processing time; authenticate and validate before a transactional durable enqueue/deduplication record. Confirm the same delivery cannot schedule two effects under concurrent workers. Acknowledge promptly after that boundary; if persistence fails, do not return a false success. Separate ingress failure/redelivery from downstream retry, terminal failure and operator reconciliation. Record delivery correlation, payload hash, accepted schema, safe event metadata and outcome references, not complete sensitive bodies or credentials. Delivery ID deduplication and business idempotency need distinct keys, scopes and retention.
## Test plan and operational limits
Exercise exact bytes, whitespace mutation, a wrong/missing/short signature, concurrent duplicates, restarted workers, reused ID with different body, late redelivery and out-of-order domain updates. Include a changed-ID replay to prove what the HMAC/ID ledger does NOT protect; do this only with the supplied public synthetic bytes, not a captured real secret/payload. A valid signature is necessary evidence of possession of the configured key, not a blanket authorization for every business operation. Require subscription and tenant mapping plus allowlisted payload schema before effects.
## Output
Return provider contract/revision, raw-byte/signature evidence, durable commit/ack boundary, deduplication and effect keys, retention/replay gaps, ordering model, negative-test results, recovery ownership and unverified behavior. Do not install a receiver, reveal a secret, change provider settings, request redelivery or replay captured traffic from this review. See [GitHub validation](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries) and [delivery best practices](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks); the local model is not production-grade ingress or proof of downstream reliability.
Real example
Input
Review these public synthetic bytes and expected delivery boundaries, not a live webhook.
{
"provenance": "synthetic minimal payload and public demo key; not a captured GitHub delivery",
"deliveryId": "fixture-delivery-1",
"rawBodyUtf8": "{\"repository\":{\"id\":7},\"pull_request\":{\"id\":42,\"head\":{\"sha\":\"fixture-head-1\"}},\"action\":\"opened\"}",
"signature": "sha256=b32b11578705af5125070e3699299c751dd52718f8919f352f07ed509fc05976",
"practiceKey": "synthetic-practice-key-NOT-A-PRODUCTION-SECRET",
"receiverPolicy": "Validate raw bytes before parse; durable subscription-scoped delivery deduplication; bounded ingress and queue; no expensive synchronous processing; business consumer idempotency required separately."
}Expected result
Authenticity primitive: HMAC-SHA256 over the EXACT supplied raw UTF-8 bytes validates against the public practice key/signature. Parsing and pretty-printing the same JSON changes bytes and fails that original signature. Missing, malformed or changed-body signatures must be rejected before queue writes. The practice key is public teaching input, never a usable production secret. Delivery model: first verified fixture-delivery-1 -> QUEUED_MODEL_ONLY; same ID/same bytes -> DUPLICATE_NO_NEW_WORK; same ID/different correctly signed bytes -> STOP_ID_BODY_CONFLICT. A real receiver needs an atomic durable uniqueness/transaction boundary across all workers and a reviewed retention period. A process-local Map loses state on restart and does not demonstrate that boundary. A2xx response is an ingress acknowledgement after durable acceptance, not proof that downstream processing completed. Important replay limit: the GitHub HMAC binds the payload body, not every HTTP header or a signed timestamp. A captured valid body/signature replayed with a new X-GitHub-Delivery value can pass this primitive and bypass ID-only deduplication. Do not claim that an unsigned Date header or a five-minute clock check solves this. Bound exposure with TLS, secret protection/rotation policy, durable deduplication, scoped ingress controls and idempotent business effects; document retention and late replay limitations. A payload hash alone is also not always a valid business event key because distinct legitimate events can share content. Ordering/recovery: check permitted event/action and subscription/repository context before effects. Treat X-GitHub-Event as untrusted routing input and validate the selected payload schema/context. Reconcile stale/out-of-order changes by the domain's authoritative revision/event semantics, not arrival order alone. GitHub redelivery retains the delivery ID; preserve that ID and original receipt evidence when requesting an authorized redelivery. Do not assume the provider automatically retries every failed delivery. Verification ledger: correct bytes PASS; altered whitespace FAIL under original signature; missing/short header FAIL; duplicate verified ID creates no new modeled work; changed ID demonstrates the replay limitation; restart/concurrency/durable commit/downstream retries remain unverified. No webhook endpoint, secret, provider redelivery or external effect was used.