# Guide to Doubleword Webhooks: Features and Best Practices

Doubleword runs large language model inference in batches: you upload a file of requests, and Doubleword processes them at lower cost than real-time calls, returning an output file when it's done. A batch can take a while, so instead of polling its status you can have Doubleword call a webhook when it finishes, either successfully or with a failure. Your pipeline then downloads the results and moves on.

## What are Doubleword webhooks?

Doubleword has one webhook URL per user, set on your profile next to the signing key. When any of your batches reaches a terminal state, Doubleword sends a JSON `POST` there. There is no event selection: both event types always go to the URL.

Requests follow the Standard Webhooks specification, with `webhook-id`, `webhook-timestamp` and `webhook-signature` headers. The signing code is part of Doubleword's open-source control layer, which generates each key as 32 random bytes, base64-encoded and prefixed with `whsec_`.

## Doubleword webhook features

| Feature | Details |
| --- | --- |
| Configuration | One webhook URL per user, on the [profile](https://app.doubleword.ai/profile) page |
| Events | `batch.completed` and `batch.failed`, always both |
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | `webhook-signature`, with `webhook-id` and `webhook-timestamp` |
| Secret | One signing key per user, `whsec_` plus base64 |
| Body | JSON |
| Event routing | Body field `type` |
| Retries | Exponential backoff until attempts run out. Count and timing not published |
| Auto-disable | After 10 consecutive failed deliveries |
| Alternative | Email notifications, toggled on the same page |

## Events and payloads

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `batch.completed` | A batch completes (`data.status` is `completed`) | Download `output_file_id` and `error_file_id` with the files API, start downstream processing |
| `batch.failed` | A batch fails (`data.status` is `failed`) | Alert, inspect the error file, resubmit |

Both events share one body:

```json
{
  "type": "batch.completed",
  "timestamp": "2026-01-15T12:00:00Z",
  "data": {
    "batch_id": "batch_29cd13af-5ce9-487e-98ff-4eb6730c12b4",
    "status": "completed",
    "request_counts": { "total": 100, "completed": 98, "failed": 2, "cancelled": 0 },
    "output_file_id": "file_b4213e44-3c85-4689-9cae-e6d986785143",
    "error_file_id": "file_49fdc045-77a8-409b-bb3e-d661df05f9fb",
    "created_at": "2026-01-15T10:00:00Z",
    "finished_at": "2026-01-15T12:00:00Z"
  }
}

```

This is Doubleword's documented example with its inline `//` comments removed; the published version has comments, so it isn't valid JSON as printed. A `batch.completed` event can still include failed requests: check `request_counts.failed` and the `error_file_id` file, not only `type`.

## Setting up Doubleword webhooks

1. Open your [Doubleword profile](https://app.doubleword.ai/profile).
2. Enter your webhook URL.
3. Copy the signing key, which starts with `whsec_`, and store it as `DOUBLEWORD_WEBHOOK_SECRET`.

Doubleword's docs suggest pasting a Webhook.site URL first to see a request. That shows the headers and body but doesn't check the signature. To test the full path, put a Hookdeck source in front: create one with the **Doubleword** type, paste the signing key, use the source URL on your profile, and forward it to your machine with the [Hookdeck CLI](/docs/cli):

```bash
npx hookdeck-cli listen 3000 doubleword --path /webhooks/doubleword

```

Then submit a small batch and wait for it to finish.

## Securing Doubleword webhooks

Strip `whsec_` from the signing key and base64-decode the rest. Compute HMAC-SHA256 over `<webhook-id>.<webhook-timestamp>.<raw body>`, base64-encode it, and accept the request if any `v1,` entry in `webhook-signature` matches:

```javascript
const crypto = require('node:crypto');

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

Doubleword's Flask sample builds `v1,<expected>` and compares it with the whole header. That works while there is exactly one signature, but the Standard Webhooks format allows several space-separated entries, and the function above checks each one. Neither applies a timestamp window. Doubleword doesn't specify one, and if you add one yourself, remember that Hookdeck doesn't apply a timestamp tolerance and keeps the original `webhook-timestamp` when it retries or replays a delivery.

The receiver hands finished batches to a worker that downloads the output files:

```javascript
const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

// downloads.enqueue(job) records the job and resolves once it is stored.
function createDoublewordReceiver(downloads) {
  const app = express();
  app.post('/webhooks/doubleword', express.raw({ type: '*/*' }), async (req, res) => {
    const secret = process.env.DOUBLEWORD_WEBHOOK_SECRET;
    if (!secret) return res.sendStatus(500);
    if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

    const body = parseJsonObject(req.body);
    if (!body) return res.sendStatus(400); // signed, but not a JSON object
    const { type, data } = body;
    if (!data || typeof data !== 'object') return res.sendStatus(400);
    try {
      await downloads.enqueue({
        batchId: data.batch_id,
        failed: type === 'batch.failed',
        outputFileId: data.output_file_id,
        errorFileId: data.error_file_id,
      });
    } catch {
      return res.sendStatus(503);
    }
    return res.sendStatus(200);
  });
  return app;
}

```

A Hookdeck Doubleword source answers Doubleword with `200` even when the signature is wrong. It marks the request as failed verification and keeps it from reaching your worker.

> **Make Doubleword webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) verifies every batch notification, stores it, and keeps your Doubleword webhook from being disabled while your pipeline is down.

## Doubleword webhook limitations and pain points

### Ten failures switch the webhook off

**The Problem:** After an outage or a bad deploy, batch notifications stop completely.

**Why It Happens:** Doubleword disables the webhook after 10 consecutive failed deliveries, and you have to re-enable it on your profile.

**Workarounds:**

* Check the profile after any incident and re-enable the webhook.
* Keep polling as a fallback for batches you submitted but never heard back about.

**How Hookdeck Can Help:** Hookdeck accepts each notification on arrival and retries delivery to your service itself, so your failures never reach Doubleword's count of ten.

### An unpublished retry schedule

**The Problem:** You can't tell how long Doubleword keeps trying a failed delivery.

**Why It Happens:** The docs say retries use exponential backoff and stop when attempts run out, without giving a number, schedule or response timeout.

**Workarounds:**

* Answer `2xx` immediately and download output files in the background.

**How Hookdeck Can Help:** Hookdeck's own [retry settings](/docs/retries) decide how long your service has to recover, whatever Doubleword's policy is.

### One URL per user

**The Problem:** Two pipelines, or staging and production, can't each have their own webhook.

**Why It Happens:** The webhook URL is a profile setting, and every batch you submit reports to it.

**Workarounds:**

* Route on `batch_id` in one receiver, using a lookup of which pipeline submitted each batch.

**How Hookdeck Can Help:** One Hookdeck source can fan out to several destinations, and [filters](/docs/filters) can send each batch's events to the right one.

## Best practices

### Deduplicate on `webhook-id` or `batch_id`

A retried notification keeps its `webhook-id`, and each batch reaches a terminal state once. Either works as an idempotency key. Read [how to make webhook handlers idempotent](/webhooks/guides/implement-webhook-idempotency) for the full pattern.

### Download results outside the request

Output files can be large. Store the notification, return `200`, and fetch `output_file_id` and `error_file_id` through the files API from a worker.

### Read the counts on success

`batch.completed` means the batch finished, not that every request succeeded. `request_counts` tells you how many failed or were cancelled.

## Conclusion

Doubleword's webhook has one URL and two events. Its risk is delivery: the retry schedule isn't published and ten failures disable the webhook, so acknowledge quickly and watch its status.

[Hookdeck Event Gateway](https://hookdeck.com) keeps that webhook enabled through your outages and gives you a log of every batch notification. [Start free](https://dashboard.hookdeck.com/signup).