Webhooks - cloro

When you provide a webhook.url on an async task, cloro sends an HTTP POST to your endpoint once the task reaches a terminal state — COMPLETED or FAILED. This page covers everything that happens at that endpoint: the payload shape, how to respond, how cloro retries, how to verify deliveries came from cloro, and what to check when one doesn’t arrive.

Enabling deliveries

Include a webhook.url when you create the async task:

{
  "taskType": "CHATGPT",
  "webhook": {
    "url": "https://your-app.com/webhook-handler"
  },
  "payload": { "prompt": "...", "country": "US" }
}

That’s the whole opt-in. cloro will POST the full task result to that URL when the task completes. If you omit webhook.url, fall back to polling.

Enable signing from the dashboard if your endpoint performs sensitive operations (charging, writing to your database) based on webhook content — anyone who can reach the URL could otherwise send a forged delivery.

Receiving deliveries

Your endpoint receives a JSON body containing the task metadata, credit accounting, and the full provider response:

Webhook payload

{
  "task": {
    "id": "b27a21e1-7c39-4aa2-a347-23e828c426f9",
    "taskType": "CHATGPT",
    "status": "COMPLETED",
    "priority": 5,
    "createdAt": "2025-11-10T15:00:00.000Z",
    "idempotencyKey": "your-custom-identifier-123"
  },
  "credits": {
    "creditsToCharge": 10,
    "creditsCharged": 10
  },
  "response": {
    "model": "gpt-5-3-mini",
    "text": "The weather in New York is currently sunny...",
    "html": "https://storage.cloro.dev/results/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/page-1.html",
    "sources": [],
    "shoppingCards": [],
    "entities": [],
    "markdown": "The weather in New York is currently sunny...",
    "searchQueries": ["weather in New York"]
  }
}

Responding to a webhook

Respond with any 2xx status code (typically 200 OK) to acknowledge receipt. Anything else — non-2xx, TLS errors, timeouts — counts as a failed delivery and triggers a retry.

app.post('/webhook-handler', (req, res) => {
  // Process the result asynchronously
  console.log(req.body);

  // Immediately acknowledge receipt
  res.status(200).send();
});

Retries and deduplication

cloro retries failed deliveries up to 5 attempts with exponential backoff. If an attempt fails, the next one is scheduled for:

Attempt 2: ~2 minutes later
Attempt 3: ~4 minutes later
Attempt 4: ~8 minutes later
Attempt 5: ~16 minutes later

The same logical task may therefore arrive at your endpoint multiple times. If you need exactly-once handling, deduplicate on the task.id field inside the payload. (Signed deliveries also carry an X-Cloro-Webhook-Id header that’s unique per attempt, but task.id is always available.)

Verifying deliveries

Anyone who can reach your endpoint could send a forged request that looks identical to a real cloro delivery unless you verify the signature. Webhook signing is opt-in per organization. Once enabled, every outbound delivery from cloro includes three headers your endpoint can use to confirm the payload’s origin and integrity.

Enabling signing

Webhook signing is enabled from the dashboard. When you enable it, cloro generates a secret prefixed with whsec_ and shows it to you exactly once. Copy it immediately and store it in your secret manager — it’s the only thing your endpoint needs in order to verify signatures.

Treat the signing secret like a password. Anyone with the secret can forge payloads that pass your verification check. Store it in a secret manager, not in source code. Rotate it from the dashboard if it ever leaks.

What we send

Every signed delivery includes three headers in addition to the standard Content-Type: application/json:

Header	Example	Purpose
`X-Cloro-Timestamp`	`1748419200`	Unix timestamp (seconds) when cloro signed the delivery
`X-Cloro-Signature`	`v1=ab12cd34...`	HMAC-SHA256 signature, prefixed with the scheme version
`X-Cloro-Webhook-Id`	`b27a21e1-7c39-4aa2-a347-23e828c426f9-1`	Unique delivery ID (`<task-id>-<attempt>`) for deduplication

How the signature is computed

signed_payload = "<X-Cloro-Timestamp>" + "." + "<raw_request_body>"
signature      = HMAC-SHA256(your_signing_secret, signed_payload)

cloro hex-encodes the HMAC output and ships it as the v1= portion of X-Cloro-Signature. Your endpoint recomputes the same value and compares it to the header. The timestamp goes inside the signed payload so an attacker can’t replay an intercepted webhook against you indefinitely — your endpoint can reject anything signed more than a few minutes ago.

Verification

Step 1 — capture the raw body

The signature is computed over the exact bytes of the request body. If your web framework parses the JSON and then re-serializes it before you see it (Express’s express.json() does this, as does Flask’s request.json when the body type is detected as JSON), the bytes you check can differ from the bytes cloro signed — different float formatting, key ordering, or whitespace — and verification will silently fail. Always capture the raw bytes first, then parse the JSON only after verification has passed.

Step 2 — verify the signature

import crypto from "crypto";
import express from "express";

const app = express();
const SIGNING_SECRET = process.env.CLORO_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 5 * 60; // reject anything older than 5 minutes

app.post(
  "/webhooks/cloro",
  // IMPORTANT: raw() not json() — we need the exact bytes cloro signed.
  express.raw({ type: "application/json" }),
  (req, res) => {
    const timestamp = req.header("X-Cloro-Timestamp");
    const signatureHeader = req.header("X-Cloro-Signature");
    const rawBody = req.body.toString("utf8");

    if (!timestamp || !signatureHeader) {
      return res.status(400).send("missing signature headers");
    }

    // Replay protection
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) {
      return res.status(400).send("timestamp outside tolerance");
    }

    // Compute the expected signature
    const expected = crypto
      .createHmac("sha256", SIGNING_SECRET)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

    const provided = signatureHeader.replace(/^v1=/, "");
    if (
      provided.length !== expected.length ||
      !crypto.timingSafeEqual(
        Buffer.from(expected, "utf8"),
        Buffer.from(provided, "utf8")
      )
    ) {
      return res.status(401).send("invalid signature");
    }

    // Parse JSON only after verification has passed
    const payload = JSON.parse(rawBody);
    // …handle payload…

    res.status(200).send("ok");
  }
);

The 5-minute tolerance is what we recommend — adjust if your endpoint sits behind slow networks or you want stricter replay protection.

Common pitfalls

Parsing the body before verifying — the signature is over the raw bytes. Frameworks that parse-then-restringify (Express’s express.json(), some serverless wrappers) can change byte representation and break verification. Always read the raw bytes first.
String equality instead of constant-time compare — a == comparison on the hex strings leaks information about the expected signature via timing differences. Use crypto.timingSafeEqual (Node), hmac.compare_digest (Python), or hmac.Equal (Go).
No timestamp check — without rejecting old timestamps, an attacker who intercepts even one signed webhook can replay it against you indefinitely. The timestamp is in the signed payload specifically to make this check possible.
Storing the secret in source code — if a secret leaks, rotate it immediately from the dashboard. The secret is the only thing standing between an attacker and a forged delivery.

Disabling or rotating

You can rotate or disable signing at any time from the dashboard.

Rotating generates a new secret immediately. Your existing receivers will reject signatures until you update them with the new value, so coordinate the rotation with your deploy.
Disabling stops sending the X-Cloro-* headers. Existing receivers that verify will start rejecting payloads until you remove the verification check on their side.

Troubleshooting

My webhook never arrived. What should I check?

If a task reaches COMPLETED or FAILED but you don’t see the webhook hit your endpoint, work through these in order:

Look up the task. Call GET /v1/async/task/{taskId} — if the status is terminal, the result already exists and you can fetch it during the 24-hour retention window.
Check the URL you submitted. Typos, missing protocol, and non-public hostnames (e.g., localhost) will not deliver.
Check your endpoint’s response. Non-2xx responses, TLS errors, and long timeouts can exhaust the retry budget.
Don’t assume order. Webhooks for a batch arrive in completion order, not submission order. Poll /v1/async/status if you need a count of outstanding tasks.

Need help?

Reach out at support@cloro.dev
Async requests: Making requests → Asynchronous requests
Async task reference: POST /v1/async/task
Authentication: API keys & Bearer tokens

Documentation Index

​Enabling deliveries

​Receiving deliveries

​Responding to a webhook

​Retries and deduplication

​Verifying deliveries

​Enabling signing

​What we send

​How the signature is computed

​Verification

​Step 1 — capture the raw body

​Step 2 — verify the signature

​Common pitfalls

​Disabling or rotating

​Troubleshooting

​My webhook never arrived. What should I check?

​Need help?

Enabling deliveries

Receiving deliveries

Responding to a webhook

Retries and deduplication

Verifying deliveries

Enabling signing

What we send

How the signature is computed

Verification

Step 1 — capture the raw body

Step 2 — verify the signature

Common pitfalls

Disabling or rotating

Troubleshooting

My webhook never arrived. What should I check?

Need help?