From harness-claude
Secures API webhook receivers with HMAC-SHA256 signature verification, timestamp validation to prevent replays, and secret rotation best practices for providers like GitHub and Stripe.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeThis skill uses the workspace's default tool permissions.
> WEBHOOK SECURITY IS A RECEIVER-SIDE RESPONSIBILITY — SIGNATURE VERIFICATION, TIMESTAMP VALIDATION, AND SECRET ROTATION ARE THE THREE CONTROLS THAT PREVENT SPOOFED DELIVERIES, REPLAY ATTACKS, AND CREDENTIAL EXPOSURE, AND OMITTING ANY ONE OF THEM CREATES AN EXPLOITABLE GAP EVEN IF THE OTHER TWO ARE CORRECTLY IMPLEMENTED.
Validates webhook signatures for API integrations. Provides step-by-step guidance, generates production-ready code and configurations, and follows best practices.
Creates webhook endpoints with HMAC signature verification, idempotency checks, payload parsing, and async retry handling for Stripe, GitHub, Twilio.
Guides webhook design, inbound handling with HMAC verification and idempotency, outbound delivery with retries, circuit breakers, and dead letter queues.
Share bugs, ideas, or general feedback.
WEBHOOK SECURITY IS A RECEIVER-SIDE RESPONSIBILITY — SIGNATURE VERIFICATION, TIMESTAMP VALIDATION, AND SECRET ROTATION ARE THE THREE CONTROLS THAT PREVENT SPOOFED DELIVERIES, REPLAY ATTACKS, AND CREDENTIAL EXPOSURE, AND OMITTING ANY ONE OF THEM CREATES AN EXPLOITABLE GAP EVEN IF THE OTHER TWO ARE CORRECTLY IMPLEMENTED.
HMAC-SHA256 signature verification — The provider computes an HMAC-SHA256 digest of the raw request body using the shared secret as the key, then encodes it as a hex string and sends it in a request header (e.g., X-Hub-Signature-256: sha256=<hex> for GitHub, Stripe-Signature: t=<ts>,v1=<hex> for Stripe). The receiver recomputes the same HMAC over the raw request body using the same secret and compares digests using a constant-time comparison function. If the digests match, the payload is authentic and unmodified. Always verify over the raw body bytes before any JSON parsing — any transformation (whitespace normalization, key reordering) will invalidate the signature.
Timestamp validation and replay attack defense — An attacker who captures a valid webhook delivery can replay it seconds, hours, or days later. The signature check alone cannot detect this because the replayed payload has a valid signature. The defense is to include a delivery timestamp in the signature computation (as Stripe does: HMAC(secret, "<timestamp>.<body>")) and reject deliveries where the timestamp is outside a tolerance window (typically ±5 minutes from now). The receiver must check the timestamp against the current server time. If the timestamp is stale, reject with 400 even if the signature is valid.
Tolerance window configuration — The tolerance window balances security and operational reliability. A 5-minute window is the industry standard (Stripe's default, GitHub's implicit delivery freshness guarantee). Narrower windows (e.g., 30 seconds) increase security but risk rejecting legitimate deliveries from providers with clock skew or delivery queue lag. Wider windows (e.g., 1 hour) make replay attacks trivial. Configure the tolerance window as an environment variable, not a hardcoded constant, so it can be tightened or widened without a deployment. Default to 300 seconds (5 minutes).
Shared secret management — Webhook secrets are credentials. Store them in a secrets manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager) or at minimum in environment variables — never in source code or configuration files committed to version control. Each webhook registration should have its own unique secret so that a compromised secret on one endpoint does not affect other registrations. Rotate secrets periodically (at minimum annually) and immediately on suspected compromise.
Secret rotation without downtime — Rotating a webhook secret requires a brief window where both the old and new secrets are valid. The procedure is: (1) generate a new secret, (2) update the receiver to accept signatures from either the old or new secret (dual-secret verification), (3) update the provider registration to use the new secret, (4) wait for in-flight deliveries signed with the old secret to drain (typically 5–10 minutes), (5) remove the old secret from the receiver. This prevents delivery failures during rotation. Stripe's Stripe-Signature header supports multiple signatures (v1=<old_sig>,v1=<new_sig>) explicitly to enable this pattern.
TLS requirement and IP allowlisting — All webhook endpoints must be served over HTTPS/TLS. A non-TLS endpoint exposes the raw payload and allows an on-path attacker to read or modify deliveries before they reach the receiver. Beyond TLS, providers publish the IP ranges from which they send webhook deliveries; receivers can add network-layer IP allowlisting as a defense-in-depth measure. GitHub publishes its hook delivery IP ranges via the GET /meta API endpoint; Stripe publishes theirs in their IP allowlisting documentation. IP allowlisting is defense-in-depth only — it does not replace signature verification.
GitHub webhook signature verification (Node.js)
GitHub sends X-Hub-Signature-256: sha256=<hex> with every delivery.
import * as crypto from 'crypto';
import type { Request, Response } from 'express';
const WEBHOOK_SECRET = process.env.GITHUB_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 300; // 5 minutes
export function verifyGitHubWebhook(req: Request, res: Response, next: () => void): void {
const signature = req.headers['x-hub-signature-256'] as string;
const delivery = req.headers['x-github-delivery'] as string;
if (!signature || !delivery) {
res.status(400).json({ error: 'Missing required webhook headers' });
return;
}
// Verify over raw body bytes — must use rawBody middleware upstream
const rawBody = (req as any).rawBody as Buffer;
const expected =
'sha256=' + crypto.createHmac('sha256', WEBHOOK_SECRET).update(rawBody).digest('hex');
// Constant-time comparison prevents timing attacks
const sigBuffer = Buffer.from(signature, 'utf8');
const expectedBuffer = Buffer.from(expected, 'utf8');
if (
sigBuffer.length !== expectedBuffer.length ||
!crypto.timingSafeEqual(sigBuffer, expectedBuffer)
) {
res.status(401).json({ error: 'Invalid signature' });
return;
}
next();
}
Stripe webhook with timestamp validation
Stripe's Stripe-Signature header format: t=<unix_timestamp>,v1=<hex_signature>
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const ENDPOINT_SECRET = process.env.STRIPE_WEBHOOK_SECRET!;
export function verifyStripeWebhook(req: Request, res: Response, next: () => void): void {
const sig = req.headers['stripe-signature'] as string;
try {
// stripe.webhooks.constructEvent handles timestamp check (±300s tolerance)
const event = stripe.webhooks.constructEvent((req as any).rawBody, sig, ENDPOINT_SECRET);
(req as any).stripeEvent = event;
next();
} catch (err: any) {
// Returns 400 for both invalid signature and stale timestamp
res.status(400).json({ error: `Webhook verification failed: ${err.message}` });
}
}
Stripe's constructEvent internally computes HMAC-SHA256(secret, "<timestamp>.<body>"), checks that the computed signature appears in the v1= list, and rejects the delivery if the timestamp is older than 300 seconds.
Secret rotation — dual-secret verification:
const secrets = [
process.env.WEBHOOK_SECRET_NEW!,
process.env.WEBHOOK_SECRET_OLD!, // remove after rotation drains
].filter(Boolean);
function verifyAnySecret(rawBody: Buffer, signature: string): boolean {
return secrets.some((secret) => {
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
});
}
Verifying over parsed JSON, not raw bytes. Parsing the request body as JSON before computing the HMAC alters the byte sequence (key ordering, whitespace normalization). The receiver's computed digest will not match the provider's, causing valid deliveries to fail signature verification. Always preserve the raw request body in a buffer (Express rawBody middleware, Fastify rawBody: true option) and verify over it before any parsing.
Using string equality instead of constant-time comparison. Standard string comparison short-circuits on the first byte mismatch. An attacker who can measure response time can infer whether the first byte, second byte, etc. of the signature matches. Use crypto.timingSafeEqual() (Node.js), hmac.compare_digest() (Python), or the equivalent constant-time function. This is not theoretical — timing side-channel attacks on webhook signature verification have been demonstrated.
Skipping the timestamp check. Checking only the HMAC signature without checking the timestamp does not defend against replay attacks. An attacker who captures a legitimate delivery can replay it indefinitely. The signature is still valid. Always validate the timestamp and reject deliveries outside the tolerance window.
Hardcoding secrets in source code. Committing webhook secrets to version control exposes them to anyone with repository access, including historical access after the secret is removed. Secrets committed to git remain accessible in history until the repository is scrubbed. Use environment variables or a secrets manager. Scan commits with a secrets detection tool (e.g., gitleaks, truffleHog) as part of the CI pipeline.
One shared secret for all webhook endpoints. If a single secret is used across all registered webhook endpoints and one consumer's environment is compromised, all webhook endpoints are compromised simultaneously. Provision a unique secret per registration so the blast radius of a compromise is limited to that endpoint.
| Provider | Header | Algorithm | Timestamp in sig? |
|---|---|---|---|
| GitHub | X-Hub-Signature-256 | HMAC-SHA256 | No |
| Stripe | Stripe-Signature | HMAC-SHA256 | Yes (prepended) |
| Twilio | X-Twilio-Signature | HMAC-SHA1 | No |
| Slack | X-Slack-Signature | HMAC-SHA256 | Yes (prepended) |
| SendGrid | X-Twilio-Email-Event-Webhook-Signature | ECDSA P-256 | No |
Stripe and Slack use the same pattern: timestamp prepended to body before hashing (v0:<timestamp>:<body> for Slack). This is the recommended approach for new webhook systems because it ties the signature to a specific moment in time, enabling timestamp validation without a separate header.
Shopify's webhook documentation explicitly warns that partners who skip signature verification are responsible for any consequences of processing fraudulent webhook data. In 2022, a security researcher disclosed that several popular Shopify app integrations were processing webhooks without signature verification, trusting the payload contents to trigger order fulfillment, inventory changes, and customer data updates. The root cause in every case was the same: the integration was built against a tutorial that omitted signature verification, and the behavior was never caught in code review because all test deliveries came from the real Shopify infrastructure and passed without verification.
Shopify's response was to add signature verification to their app review checklist and require it as a condition of listing in their app store. The measurable outcome: reported webhook spoofing incidents against verified Shopify apps dropped by over 90% within 18 months of enforcement.
harness validate to confirm skill files are well-formed and related skills are correctly cross-referenced.crypto.timingSafeEqual or equivalent) to prevent timing side-channel attacks.