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 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:
{
"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
- Open your Doubleword profile.
- Enter your webhook URL.
- Copy the signing key, which starts with
whsec_, and store it asDOUBLEWORD_.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:
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:
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:
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 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
2xximmediately and download output files in the background.
How Hookdeck Can Help: Hookdeck's own retry settings 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_idin 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 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 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 keeps that webhook enabled through your outages and gives you a log of every batch notification. Start free.