# 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.

```javascript
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

```

```python
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/doubleword-webhooks/references/verification.md), where the window can be dropped or widened.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/doubleword-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/doubleword-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/doubleword-webhooks/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

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

```

## Local Development

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

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/doubleword-webhooks/references/overview.md) - What Doubleword webhooks are, events, payload
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/doubleword-webhooks/references/setup.md) - Profile configuration and signing key
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/doubleword-webhooks/references/verification.md) - Signature details, manual verifier, gotchas