Agent skill

Doubleword Webhooks Skill

Receive and verify Doubleword webhooks. Use when setting up Doubleword batch webhook handlers, debugging Standard Webhooks signature verification (webhook-id, webhook-timestamp, webhook-signature, whsec_ signing key), or handling batch.completed and batch.failed events.

Install this skill

npx skills add hookdeck/webhook-skills --skill doubleword-webhooks


When to Use This Skill

  • How do I receive Doubleword webhooks?
  • How do I verify Doubleword webhook signatures?
  • How do I handle batch.completed and batch.failed events?
  • Why is my Doubleword webhook signature verification failing?
  • Setting up the webhook URL and signing key on a Doubleword profile

Verification (core)

Doubleword follows Standard Webhooks. Each request has webhook-id, webhook-timestamp (Unix seconds) and webhook-signature (one or more space-separated v1,<base64> entries). The signature is HMAC-SHA256, base64-encoded, over {webhook-id}.{webhook-timestamp}.{raw body}. Always verify the raw body before parsing.

The signing key (from your profile) is whsec_ + base64: strip the prefix and base64-decode it to get the raw key. The standardwebhooks library (npm and PyPI) does this for you.

const { Webhook } = require('standardwebhooks');

// DOUBLEWORD_WEBHOOK_SECRET holds the full whsec_ value; fail closed if unset.
// Header fallback: use webhook-* and fall back to svix-* when webhook-id is absent.
const prefix = req.get('webhook-id') ? 'webhook' : 'svix';
const headers = {
  'webhook-id': req.get(`${prefix}-id`),
  'webhook-timestamp': req.get(`${prefix}-timestamp`),
  'webhook-signature': req.get(`${prefix}-signature`),
};
// rawBody: the exact request bytes as a string (express.raw({ type: '*/*' }))
new Webhook(process.env.DOUBLEWORD_WEBHOOK_SECRET).verify(rawBody, headers, { jsonParse: false });
// throws on a bad signature or a timestamp outside the window -> respond 400/401
from standardwebhooks.webhooks import Webhook

# Catch Exception: the library can raise plain ValueError on malformed signature entries.
Webhook(os.environ["DOUBLEWORD_WEBHOOK_SECRET"]).verify(raw_body, headers, json_parse=False)

Secret handling: the library base64-decodes whatever it is given, so pass the whsec_ value as-is. The examples use a secret without the whsec_ prefix as its raw UTF-8 bytes, > passing raw bytes to the library.

Header fallback: the library only reads webhook-* names. The examples read webhook-*, fall back to svix-* when webhook-id is absent, and hand the library the three values as webhook-id, webhook-timestamp and webhook-signature.

Timestamp window and Hookdeck retries: the library always enforces a fixed 5-minute timestamp window. Hookdeck retries and replays resend the original timestamp, so the library rejects a retry or replay delivered more than 5 minutes later. If your endpoint sits behind Hookdeck, use the manual verifier in references/verification.md, where the window can be dropped or widened.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

Doubleword documents two events (the list may not be exhaustive). The event type is the top-level type; data.status repeats the outcome.

EventTriggered When
batch.completedA batch finishes (data.status is completed)
batch.failedA batch fails (data.status is failed)

Payload: { type, timestamp, data }, where data has batch_id, status, request_counts, output_file_id, error_file_id, created_at and finished_at.

Delivery Behavior

Respond with any 2xx to acknowledge. Other statuses and timeouts are retried with exponential backoff until attempts run out. After 10 consecutive failed deliveries the webhook is disabled; re-enable it from your profile. Unknown event types should still get a 2xx after verification.

Environment Variables

DOUBLEWORD_WEBHOOK_SECRET=whsec_your_signing_key_here   # Signing key from your Doubleword profile, with the whsec_ prefix

Local Development

# Start a tunnel to your local handler (no account needed)
npx hookdeck-cli listen 3000 doubleword --path /webhooks/doubleword

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →