Skip to content
Skills Library
Programming · Building & coding

webhooks

/webhooks

Expert Webhooks architecture assistance covering HMAC signature verification, idempotent delivery, exponential backoff retries, and ingestion queues. Use when building webhook consumers, sending webhook notifications to third parties, or processing asynchronous event callbacks.

Licence
MIT
Last repository change
01.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 01.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Expert Webhooks architecture assistance covering HMAC signature verification, idempotent delivery, exponential backoff retries, and ingestion queues. Use when building webhook consumers, sending webhook notifications to third parties, or processing asynchronous event callbacks.

Original author description

Expert Webhooks architecture assistance covering HMAC signature verification, idempotent delivery, exponential backoff retries, and ingestion queues. Use when building webhook consumers, sending webhook notifications to third parties, or processing asynchronous event callbacks.

How it works

  1. When to Use
  2. Quick Start
  3. Core Concepts
  4. Common Patterns
  5. Best Practices
  6. Troubleshooting
  7. References
Original SKILL.md headings · 163 lines, 625 words
SKILL.md preview
---
name: webhooks
description: Expert Webhooks architecture assistance covering HMAC signature verification, idempotent delivery, exponential backoff retries, and ingestion queues. Use when building webhook consumers, sending webhook notifications to third parties, or processing asynchronous event callbacks.
---

# Webhooks

Webhooks are "user-defined HTTP callbacks". They are triggered by some event in a source system (e.g., Stripe, GitHub) and sent to a destination system (Your API) to notify it.

## When to Use

- **Third-Party Event Notification**: Consuming real-time notifications from payment providers (Stripe), Git hosts (GitHub), and SaaS platforms.
- **Asynchronous System Integration**: Triggering external partner workflows when business events occur in your application.
- **Decoupled API Callback Architecture**: Notifying long-running asynchronous clients when requested tasks finish without polling.
- **Event-Driven Microservice Ingestion**: Ingesting incoming webhook events into queue buffers for asynchronous worker processing.

## Quick Start

```typescript
// Your Webhook Handler (Receiver)
app.post(
  "/webhooks/stripe",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["stripe-signature"];

    try {
      // Verify the event came from Stripe and hasn't been tampered
      const event = stripe.webhooks.constructEvent(
        req.body,
        signature,
        START_SECRET,
      );

      if (event.type === "payment_intent.succeeded") {
        fulfillOrder(event.data.object);
      }

      res.json({ received: true });
    } catch (err) {
      res.status(400).send(`Webhook Error: ${err.message}`);
    }
  },
);
```

## Core Concepts

### Cryptographic Signature Verification (HMAC-SHA256)

Validates that webhook payloads originate from authentic senders and were not tampered with in transit:

```typescript
import crypto from "crypto";

export function verifyWebhookSignature(
  payload: string,
  signatureHeader: string,
  secret: string,
): boolean {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  // Constant-time comparison prevents timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature),
  );
}
```

### Instant 200 OK Acknowledgment with Ingestion Queues

Acknowledge incoming webhooks immediately (< 500ms) and offload heavy processing to background queues:

```typescript
app.post(
  "/webhooks/stripe",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const signature = req.headers["stripe-signature"] as string;
    if (
      !verifyWebhookSignature(req.body.toString(), signature, WEBHOOK_SECRET)
    ) {
      return res.status(400).send("Invalid signature");
    }

    // Push to Redis queue immediately
    await webhookQueue.add(
      "process-stripe-event",
      JSON.parse(req.body.toString()),
    );
    res.status(200).send("Received");
  },
);
```

### Exponential Backoff Retry Strategy

Senders automatically retry failed delivery attempts with exponential delay:

```text
Attempt 1: Immediately
Attempt 2: 15 seconds later
Attempt 3: 1 minute later
Attempt 4: 15 minutes later
Attempt 5: 1 hour later -> DLQ
```

## Common Patterns

### Idempotent Webhook Processing with Deduping

**Problem**: Webhook providers retry delivery on timeout, causing duplicate state changes or double processing.

**Solution**:
Check incoming delivery event IDs against a fast cache or database before executing business logic:

```typescript
import { Request, Response } from "express";

export async function handleWebhook(req: Request, res: Response) {
  const eventId = req.headers["x-webhook-id"] as string;
  const isDuplicate = await redisClient.set(`webhook:${eventId}`, "1", {
    NX: true,
    EX: 86400, // 24-hour expiration
  });

  if (!isDuplicate) {
    return res.status(200).json({ status: "already_processed" });
  }

  // Enqueue for asynchronous background worker processing
  await taskQueue.add("process-event", req.body);
  return res.status(202).json({ status: "accepted" });
}
```

## Best Practices

**Do**:

- Verify Signatures Using Raw Unparsed Request Bodies: Never verify HMAC signatures on parsed JSON objects; whitespace discrepancies break hashes.
- Implement Idempotency Handling: Record incoming webhook event IDs in Redis or database unique indexes to discard duplicates.
- Respond with 200 OK Immediately: Queue the event for background processing; third parties time out after 5-10 seconds.
- Expose Webhook Delivery Logs: Provide dashboard interfaces where customers can view delivery status, response codes, and manual retries.

**Don't**:

- Perform heavy business logic in the HTTP handler: Long processing times cause webhook timeouts and unnecessary retries.
- Accept webhooks over insecure HTTP: Enforce TLS (HTTPS) on all webhook ingestion endpoints.
- Trust unverified webhook headers: Always use cryptographic signatures rather than relying on IP whitelists alone.

## Troubleshooting

| Error                           | Cause                       | Solution                                                        |
| :------------------------------ | :-------------------------- | :-------------------------------------------------------------- |
| `Signature Verification Failed` | Body parsing issue.         | Ensure you verify the **Raw Body**, not the parsed JSON object. |
| `Timeout`                       | Processing taking too long. | Move logic to a background job; return 200 immediately.         |

## References

- [Stripe Webhooks Guide](https://stripe.com/docs/webhooks)
- [Standard Webhooks](https://www.standardwebhooks.com/)

Versions

RepositoryScoreLicence
This page · G1Joshi/Agent-Skills100MIT
ericrisco/rsc-harness100MIT
vaisala-xweather/xweather-agent-skills100MIT
envigoinnovations/subscriby-agentic-kit100MIT
agile-4/opem-agent-plugin100MIT
ciro-maciel/ccm-stack100MIT
nirholas/xactions100Apache-2.0
claude-dev-suite/claude-dev-suite100MIT
nahid-sparktales/agent-dispatcher90MIT

Database snapshot: 13.11.2026 · package version d51befab249a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100webhooks-and-events
    This skill should be used when the user is designing webhook systems, implementing webhook signing with HMAC-SHA256, building webhook retry logic, choosing event naming conventions, handling webhook ordering, implementing webhook endpoints, or building event-driven API…
  • 100klaviyo-webhooks-events
    Implement Klaviyo webhooks with HMAC-SHA256 signature verification and event handling. Use when setting up webhook endpoints, handling Klaviyo event notifications, or creating event-driven integrations with Klaviyo. Trigger with phrases like "klaviyo webhook", "klaviyo events",…
  • 100webhook-platform-design
    Design a provider-side outbound webhook platform - event taxonomy and catalog, payload envelope and schema versioning, an HMAC signing scheme (Standard Webhooks), at-least-once delivery with retry/backoff and dead-letter policy, subscription lifecycle states, and the…
  • 100spree-events-webhooks
    Build with Spree's event bus and Webhooks 2.0 — `Spree::Events` publication, `Spree::Subscriber` DSL with `subscribes_to` and `on`, wildcard matching, lifecycle events (`{model}.created/.updated/.deleted` via `publishes_lifecycle_events`), the canonical event catalog (order.*,…
  • 100sendcloud-webhooks
    Receive and verify Sendcloud shipping webhooks. Use when setting up a Sendcloud webhook endpoint, debugging Sendcloud-Signature HMAC-SHA256 verification, or handling actions like parcel_status_changed, return_created, integration_connected, integration_updated and integration_deleted.
  • 100opnform-webhooks
    Receive and verify OpnForm webhooks. Use when setting up OpnForm webhook integration handlers, debugging X-Webhook-Signature (sha256=<hex>) HMAC verification, or handling OpnForm form submission payloads.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.