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.completedandbatch.failedevents? - 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 thewhsec_prefix as its raw UTF-8 bytes, > passing raw bytes to the library.
Header fallback: the library only reads
webhook-*names. The examples readwebhook-*, fall back tosvix-*whenwebhook-idis absent, and hand the library the three values aswebhook-id,webhook-timestampandwebhook-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.
| Event | Triggered When |
|---|---|
batch.completed | A batch finishes (data.status is completed) |
batch.failed | A 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
- references/overview.md - What Doubleword webhooks are, events, payload
- references/setup.md - Profile configuration and signing key
- references/verification.md - Signature details, manual verifier, gotchas