Verified:GitHub

webhook-integration

Design and validate inbound webhook handlers for signature, duplicate, and retry issues.

1|Updated May 6, 2026

Search Tags:#idempotency #signature verification #quarantine #hmac #webhook handler #retry contract #pii capture

One-click install

npx skills add https://github.com/jacob-balslev/skill-graph --skill webhook-integration-jacob-balslev

Or copy as Structured Prompt for Agent▼

Please help me install this Agent Skill.
Skill: webhook-integration
Source: https://github.com/jacob-balslev/skill-graph/tree/main/marketplace/skills/webhook-integration
Command: npx skills add https://github.com/jacob-balslev/skill-graph --skill webhook-integration-jacob-balslev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Webhook handlers commonly cause silent data loss by mishandling signature verification, retry/status-code contracts, and idempotency during duplicate deliveries. This Skill helps you implement a resilient inbound webhook pipeline that safely accepts provider requests while preserving raw evidence for audits and debugging.

Core Features & Use Cases

Signature verification on raw bytes: Verifies HMAC/SDK/round-trip schemes against the unparsed request body using constant-time comparison to prevent forgeries and timing leaks.
Idempotency for duplicate delivery: Implements reliable deduplication so repeated webhook attempts return success (skipped) without re-triggering side effects.
Correct retry-contract responses + quarantine: Selects appropriate permanent vs retryable HTTP responses and quarantines unverifiable/malformed events for audit without cascading failures.
Raw-then-canonical persistence: Persists raw payloads before canonical mapping so canonicalization bugs or schema drift do not destroy original provider data.
PII capture timing and secret rotation support: Captures PII synchronously on first verified receipt and supports current/previous secrets during rotation windows.

Quick Start

Use the webhook-integration skill to design and review an inbound webhook handler that verifies signatures on the raw request body, deduplicates safely, persists raw payloads before canonical mapping, and returns the provider-correct HTTP status codes while quarantining unverifiable events.

Frequently Asked Questions about webhook-integration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I verify webhook signatures without timing leaks?▼

To prevent silent data loss, webhook handlers must verify signatures on raw bytes, implement stable deduplication before side effects, select correct 4xx vs 5xx retry responses, and quarantine unverifiable events for audit without cascading failures.

How do I handle duplicate webhook deliveries without triggering side effects twice?▼

Correct retry-contract responses require selecting permanent 4xx HTTP status codes for malformed payloads and retryable 5xx codes for transient failures, while quarantining unverifiable events to audit storage without cascading into provider retries.

How do I persist raw webhook payloads before canonical mapping?▼

Webhook handlers should capture PII synchronously on first verified receipt and support current and previous secret rotation windows to maintain continuity during HMAC key updates.

What HTTP status codes should my webhook handler return for invalid signatures?▼

Unverifiable or malformed webhook events should be moved to best-effort quarantine storage for audit and debugging, ensuring that quarantine failures never cascade into provider retry loops.