Webhooks

curl --request POST \
  --url https://api.parallel.ai/v1/tasks/runs \
  --header "Content-Type: application/json" \
  --header "parallel-beta: webhook-2025-08-12" \
  --header "x-api-key: PARALLEL_API_KEY" \
  --data '{
    "task_spec": {
      "output_schema": "Find the GDP of the specified country and year"
    },
    "input": "France (2023)",
    "processor": "core",
    "metadata": {
      "key": "value"
    },
    "webhook": {
      "url": "https://your-domain.com/webhooks/parallel",
      "event_types": ["task_run.status"]
    }
  }'

import crypto from "crypto";

function computeSignature(
  secret: string,
  webhookId: string,
  webhookTimestamp: string,
  body: string | Buffer
): string {
  const payload = `${webhookId}.${webhookTimestamp}.${body.toString()}`;
  const digest = crypto.createHmac("sha256", secret).update(payload).digest();
  return digest.toString("base64"); // standard Base64 with padding
}

function isValidSignature(
  webhookSignatureHeader: string,
  expectedSignature: string
): boolean {
  // Header may contain multiple space-delimited entries; each is "v1,<sig>"
  const signatures = webhookSignatureHeader.split(" ");

  for (const part of signatures) {
    const [, sig] = part.split(",", 2);
    if (
      crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSignature))
    ) {
      return true;
    }
  }

  return false;
}

// Example usage in an Express endpoint
import express from "express";

const app = express();

app.post(
  "/webhooks/parallel",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const webhookId = req.headers["webhook-id"] as string;
    const webhookTimestamp = req.headers["webhook-timestamp"] as string;
    const webhookSignature = req.headers["webhook-signature"] as string;
    const secret = process.env.PARALLEL_WEBHOOK_SECRET!;

    const expectedSignature = computeSignature(
      secret,
      webhookId,
      webhookTimestamp,
      req.body
    );

    if (!isValidSignature(webhookSignature, expectedSignature)) {
      return res.status(401).send("Invalid signature");
    }

    // Parse and process the webhook payload
    const payload = JSON.parse(req.body.toString());
    console.log("Webhook received:", payload);

    // Process the task run status update
    if (payload.type === "task_run.status") {
      const taskRun = payload.data;
      console.log(`Task ${taskRun.run_id} status: ${taskRun.status}`);

      // Your business logic here
    }

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