Constaia

Webhooks

Receive signed events from Constaia: each event's body, Standard Webhooks signature verification in seven languages, retries, idempotency and testing.

Esta página ainda não está traduzida para o seu idioma. Mostramos-lhe a versão em inglês.

Constaia notifies you with a POST request to your server when something finishes: an asynchronous analysis, a batch, an analysis that needs human review, or a balance running low. Webhooks follow the Standard Webhooks specification: webhook-id, webhook-timestamp and webhook-signature headers, HMAC-SHA256 signature.

You need them if you use async: true, batches, or if a synchronous analysis takes longer than 30 s and answers 202.

Create an endpoint in the dashboard or with POST /v1/webhook-endpoints. Pick the events and store the whsec_… secret, which is shown only once.

Receive the POST on a public https route of your backend and read the body raw, unparsed.

Verify the signature with the secret. If it is not valid, answer 400 and discard the event.

Answer 2xx right away and process the event in the background. Deduplicate on webhook-id.

Events

EventWhen it is sentdata
analysis.completedAn analysis or classification that is not part of a batch finishes.analysis object (or classification).
analysis.review_requiredAn analysis finishes with a review verdict, including when it was computed without expect against the detected type (verdict.basis: "detected"). Sent in addition to analysis.completed (and also for batch documents).analysis object.
analysis.reviewedA person decides a human review (approves or rejects), from the dashboard or through the API.analysis object after the decision, with review and verdict.final_status.
analysis.failedAn analysis fails, including batch ones. It is not charged.analysis object with status: "failed" and error.
batch.completedEvery document of a batch has finished.batch object.
credits.lowThe balance drops below the threshold set in the dashboard. Live mode only, once until you top up.object, credits_available (packs), free_tier_remaining, credits_spendable and threshold.
verification_link.completedA verification link is completed: all its documents are finished.verification_link object plus results (each document's analysis, if include_results) and dossier (the dossier verdict).
verification_link.expiredA verification link expires without being completed.Same as verification_link.completed, with whatever was uploaded.

Every body has the same shape: type, created_at and data. Batch documents do not emit analysis.completed: wait for batch.completed.

The verification_link.* events can also be received without an endpoint, on each link's callback_url, with the same body, the same signature and the same retries. Which secret signs them is below; the full body and how to verify it are in Create links via API and receive the results.

reasons and checks messages come in the language the analysis was created with.

Headers

HeaderValue
webhook-idDelivery id, msg_…. It is the same on every retry: use it to deduplicate.
webhook-timestampTime of sending, in Unix seconds. It changes on each retry.
webhook-signaturev1,<base64 signature>. It may carry several space-separated signatures; one match is enough.
content-typeapplication/json
user-agentConstaia-Webhooks/1.0 (+https://constaia.com/docs/webhooks)

How the signature is computed

Strip the whsec_ prefix from the secret and base64-decode the rest. Those bytes are the HMAC key. Do not use the secret text as is.

Build the signed content: {webhook-id}.{webhook-timestamp}.{body}, with the body exactly as received (raw bytes, not parsed and re-serialised).

Compute HMAC-SHA256(key, content) and encode the result in base64 (not hex).

Split webhook-signature on spaces. For each v1,<signature> entry, compare <signature> with yours in constant time. If none matches, reject.

Also reject if webhook-timestamp is more than 5 minutes (300 s) away from your clock. This prevents replay attacks.

Verify with the SDKs

The SDKs do all five steps and return the parsed event, or throw an error if anything is off.

server.ts
import express from "express";
import { Constaia, WebhookVerificationError, type WebhookEvent } from "@constaia/sdk";

const app = express();
const constaia = new Constaia();
const secret = process.env.CONSTAIA_WEBHOOK_SECRET!;

// express.raw: the body arrives as a Buffer, unparsed
app.post("/webhooks/constaia", express.raw({ type: "application/json" }), async (req, res) => {
  let event: WebhookEvent<any>;
  try {
    event = await constaia.webhooks.verify(req.body, req.headers, secret);
  } catch (err) {
    const status = err instanceof WebhookVerificationError ? 400 : 500;
    return res.sendStatus(status);
  }

  res.sendStatus(204);
  void handleEvent(req.header("webhook-id")!, event).catch(console.error);
});

async function handleEvent(deliveryId: string, event: WebhookEvent<any>) {
  // Deduplicate on deliveryId in your database before processing
  switch (event.type) {
    case "analysis.completed":
      console.log(deliveryId, event.data.id, event.data.verdict?.status);
      break;
    case "analysis.review_required":
      console.log("To review:", event.data.id);
      break;
    case "analysis.failed":
      console.log("Failed:", event.data.id, event.data.error?.code);
      break;
    case "batch.completed":
      console.log("Batch finished:", event.data.id, event.data.counts);
      break;
    case "credits.low":
      console.log("Low balance:", event.data.credits_available);
      break;
  }
}

app.listen(3000);

verifyWebhook(payload, headers, secret, { tolerance }) does the same without instantiating the client: import { verifyWebhook } from "@constaia/sdk".

Verify without an SDK

Complete implementations of the algorithm. They all take the raw body.

verify-constaia.ts
import { createHmac, timingSafeEqual } from "node:crypto";

type Headers = Record<string, string | string[] | undefined>;

export function verifyConstaiaWebhook(rawBody: Buffer | string, headers: Headers, secret: string, tolerance = 300) {
  const get = (name: string) => {
    const value = headers[name];
    return Array.isArray(value) ? value[0] : value;
  };
  const id = get("webhook-id");
  const timestamp = get("webhook-timestamp");
  const signatures = get("webhook-signature");
  if (!id || !timestamp || !signatures) throw new Error("Missing webhook headers");

  const ts = Number(timestamp);
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > tolerance) {
    throw new Error("webhook-timestamp outside tolerance");
  }

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = Buffer.from(
    createHmac("sha256", key).update(`${id}.${timestamp}.`).update(rawBody).digest("base64"),
  );

  const valid = signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature);
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
  if (!valid) throw new Error("Invalid signature");

  return JSON.parse(rawBody.toString());
}

IncomingMessage headers (Node, Express) are already lowercase.

The raw body, framework by framework

The most common mistake is verifying a body your framework has already parsed and re-serialised: whitespace, order or escaping change and the signature stops matching. Always read the original bytes:

FrameworkHow to read the raw body
Expressexpress.raw({ type: "application/json" }) on the webhook route. If you use a global app.use(express.json()), register the webhook route before it.
Next.js (App Router)const raw = await req.text() in route.ts. Do not call req.json() first.
Next.js (Pages Router)export const config = { api: { bodyParser: false } } and read the req stream.
Fastify / HonoFastify: an addContentTypeParser with parseAs: "buffer" inside a plugin that only contains the webhook route. Hono: await c.req.text().
Laravel$request->getContent(), never $request->all(). Put the route in routes/api.php or exclude it from CSRF.
Symfony$request->getContent().
Djangorequest.body, with @csrf_exempt on the view.
Flask / FastAPIrequest.get_data() / await request.body().
Railsrequest.raw_post, in a controller without protect_from_forgery.
Spring Boot@RequestBody byte[] body.
ASP.NET CoreCopy Request.Body into a MemoryStream before any binding.

Guides with the full webhook route: Express, Next.js, Laravel, Django.

A verification link with a callback_url receives verification_link.completed and verification_link.expired at that URL, even if you have no endpoint. The callback is just another webhook: same body, same Standard Webhooks headers, same retries and the same verifier in the SDKs (webhooks.verify, or its alias verificationLinks.verifyCallback / verification_links.verify_callback). The only difference is which secret signs it, chosen on each delivery according to the link's mode (test or live):

  1. If the account has active webhook endpoints in that mode, the secret of the oldest one: the whsec_… you saved when you created it.
  2. If it has none, the account callback secret (whsec_…).

The account callback secret is in the dashboard, under Developers → Webhooks, in the Verification link callback secret card. There you see, for test and for live, whether callbacks are signed with an endpoint (and which one) or with the account secret; you can reveal the secret and rotate it (owners and admins). When you rotate it, the old one stops working immediately, pending retries included: update it on your server.

Because the secret is resolved on each delivery, creating your first endpoint in a mode changes the secret of that mode's callbacks. If you receive callbacks without endpoints and are about to create one, get your server ready to accept both secrets during the switch. Each link's detail in the dashboard shows the callback deliveries with their response code, and you can resend them.

Deliveries and retries

  • A delivery succeeds if your server answers any 2xx within 15 seconds. Redirects are not followed and count as a failure, just like a 4xx, a 5xx or a timeout.
  • If it fails, it is retried after: 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h, 12 h, 12 h, 10 h and 10 h. That is 12 attempts over about 3 days. After that the delivery is marked failed.
  • If you disable or delete the endpoint, its pending deliveries are marked as failed.
  • The dashboard shows the last 100 deliveries of each endpoint with their response code.
  • Deliveries that carry analysis results are emptied 7 days after being delivered, or earlier if you delete those results. See Advanced privacy.

Good practices

  • Answer fast. Verify, store the event or put it in a queue, answer 204 and process afterwards. If your logic takes longer than 15 s, Constaia counts it as a failure and retries.
  • Be idempotent. The same event can arrive more than once (for example, if you answered late). Store the processed webhook-id values and discard repeats.
  • Do not rely on order. With retries, an old event can arrive after a newer one. If you need the current state, call GET /v1/analyses/{id}.
  • Treat data as the source. The event carries the full object; you do not need another call except to refresh it.
  • Protect the exports URLs. They expire after 24 h and need no key: do not write them to public logs.

Testing your webhooks

Test mode

Endpoints created with a ck_test_ key receive events from analyses made with test keys. That way you test the whole flow for free: analyse dni_valid.jpg with async: true and you will receive analysis.completed; blurry.jpg also triggers analysis.review_required. See Test mode. To receive them on your machine, expose your local server with an https tunnel.

Test event

From the dashboard you can send a type: "test" event to any endpoint. It is signed like real ones, sent once, and is useful to check the URL and your verification.

Signing your own payloads

For automated tests, the SDKs generate valid headers for a payload and a secret:

webhook.test.ts
import { signWebhook } from "@constaia/sdk";

const secret = process.env.CONSTAIA_WEBHOOK_SECRET!;
const payload = JSON.stringify({
  type: "analysis.completed",
  created_at: new Date().toISOString(),
  data: { id: "an_test", object: "analysis", status: "completed", verdict: null, metadata: {} },
});

const headers = await signWebhook(payload, secret, { id: "msg_test_1" });
const res = await fetch("http://localhost:3000/webhooks/constaia", {
  method: "POST",
  headers: { ...headers, "content-type": "application/json" },
  body: payload,
});
console.log(res.status); // 204

Use the secret of a test endpoint. Never put the production secret in tests or repositories.

Next steps

Nesta página