Gareth Wilson Gareth Wilson

Guide to Doubleword Webhooks: Features and Best Practices

Published


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

FeatureDetails
ConfigurationOne webhook URL per user, on the profile page
Eventsbatch.completed and batch.failed, always both
SignatureStandard Webhooks HMAC-SHA256
Signature headerwebhook-signature, with webhook-id and webhook-timestamp
SecretOne signing key per user, whsec_ plus base64
BodyJSON
Event routingBody field type
RetriesExponential backoff until attempts run out. Count and timing not published
Auto-disableAfter 10 consecutive failed deliveries
AlternativeEmail notifications, toggled on the same page

Events and payloads

EventTriggered WhenCommon Use Cases
batch.completedA batch completes (data.status is completed)Download output_file_id and error_file_id with the files API, start downstream processing
batch.failedA 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

  1. Open your Doubleword 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:

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 2xx immediately 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_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 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.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.