Webhooks API v1

Crear un endpoint

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/webhooks/public/webhook-endpoints \
  -H "x-api-key: cazvid_jb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/cazvid",
    "description": "ATS application sync",
    "events": ["application.received"],
    "workspaceIds": ["WORKSPACE_ID"]
  }'

Respuesta (el secreto se devuelve una vez)

{
  "id": "66a1f0c9e4b0a1d2c3e4f5a6",
  "url": "https://hooks.example.com/cazvid",
  "description": "ATS application sync",
  "events": ["application.received"],
  "workspaceIds": ["66936c2f8a1b4e0011aa2b3c"],
  "status": "pending_verification",
  "apiVersion": "v1",
  "secret": "whsec_9tJ0k3mX2pQ7rL5nV8wZ1yB4cD6eF0g",
  "createdAt": "2026-07-09T14:20:11.004Z",
  "updatedAt": "2026-07-09T14:20:11.004Z"
}

Enviar una prueba (ping)

curl -X POST https://aio-backend-prod.cazvid.app/api/v3.0/webhooks/public/webhook-endpoints/ENDPOINT_ID/test \
  -H "x-api-key: cazvid_jb_..."

application.received

Se envía cuando un candidato completa una postulación a uno de tus empleos, tanto en el flujo de postulación de escritorio como en el móvil. candidate.email es la clave estable de la persona y application.id identifica la postulación; consulta IDs y recursos para saber cómo tratar cada campo. screeningAnswers está vacío cuando el empleo no tiene preguntas de filtro.

{
  "id": "evt_7f3a9c2e1b6d4f80a5c3e9d1f2b4a6c8",
  "type": "application.received",
  "apiVersion": "v1",
  "createdAt": "2026-07-09T14:32:07.812Z",
  "occurredAt": "2026-07-09T14:32:06.104Z",
  "organizationId": "6462916b41d57a6091c3d18a",
  "data": {
    "application": {
      "id": "66a1f0c9e4b0a1d2c3e4f5a6",
      "listItemId": "66a1f0c9e4b0a1d2c3e4f5b7",
      "url": "https://desktop.cazvid.app/employer/applicants/66a1f0c9e4b0a1d2c3e4f5a6",
      "appliedAt": "2026-07-09T14:32:06.104Z",
      "source": "one_tap",
      "qualificationStatus": "qualified",
      "screeningAnswers": [
        {
          "questionId": "6698c1a2f0b7d90012ab34ce",
          "question": "Do you have at least 2 years of customer support experience?",
          "answer": "Yes",
          "questionType": "boolean",
          "answerKind": "boolean",
          "required": true,
          "disqualifying": true
        }
      ]
    },
    "job": {
      "postId": "6698c1a2f0b7d90012ab34cd",
      "url": "https://cazvid.com/job/senior-customer-support-specialist",
      "title": "Senior Customer Support Specialist",
      "locationName": "Mexico City, Mexico",
      "countryCode": "MX",
      "isRemote": false,
      "workspaceId": "66936c2f8a1b4e0011aa2b3c"
    },
    "candidate": {
      "publicId": "pc1.ZXhhbXBsZS1vcGFxdWUtaGFuZGxlLXRva2Vu",
      "name": "Maria Gonzalez",
      "email": "maria.gonzalez@example.com",
      "phoneNumber": "+52 55 1234 5678",
      "locationName": "Mexico City, Mexico",
      "countryCode": "MX",
      "resumeUrl": "https://aio-backend-prod.cazvid.app/api/v3.0/webhooks/public/assets/eyJhbGciOi...",
      "videoUrl": "https://ik.imagekit.io/cazvid/candidate-videos/66a1f0c9.mp4"
    }
  }
}

webhook.verify

Se envía cuando creas o vuelves a verificar un endpoint. Devuelve la cadena exacta de data.challenge en el cuerpo de tu respuesta 2xx para activar el endpoint. Hasta entonces no se entrega ningún evento real.

{
  "id": "evt_2b9d4f8a1c6e0d3b5f7a9c1e2d4b6a8c",
  "type": "webhook.verify",
  "apiVersion": "v1",
  "createdAt": "2026-07-09T14:20:12.507Z",
  "occurredAt": "2026-07-09T14:20:12.507Z",
  "organizationId": "6462916b41d57a6091c3d18a",
  "data": {
    "challenge": "whc_c1f4a8e2b6d0937f5a1c9e3d7b2408af"
  }
}

webhook.ping

Se envía con la acción de prueba para que confirmes tu receptor y la verificación de firma de extremo a extremo. data.test siempre es true y los pings nunca cambian el estado de suspensión de un endpoint.

{
  "id": "evt_5c1e9a2d7f4b0836a9c3e1d5f7b2408a",
  "type": "webhook.ping",
  "apiVersion": "v1",
  "createdAt": "2026-07-09T14:25:00.113Z",
  "occurredAt": "2026-07-09T14:25:00.113Z",
  "organizationId": "6462916b41d57a6091c3d18a",
  "data": {
    "test": true
  }
}

Node

import { Webhook } from "standardwebhooks";
import express from "express";

// The secret is the whsec_... value returned at create / rotate-secret. The
// library strips the prefix and base64-decodes it to the raw key for you.
const wh = new Webhook(process.env.CAZVID_WEBHOOK_SECRET);

const app = express();
app.post(
  "/cazvid-webhooks",
  express.raw({ type: "application/json" }), // verify the RAW body
  (req, res) => {
    try {
      const event = wh.verify(req.body, {
        "webhook-id": req.header("webhook-id"),
        "webhook-timestamp": req.header("webhook-timestamp"),
        "webhook-signature": req.header("webhook-signature"),
      });
      // event is the verified envelope. Dedupe on event.id, then ACK fast.
      res.sendStatus(200);
    } catch {
      res.sendStatus(400);
    }
  },
);

Python

from standardwebhooks import Webhook

# The secret is the whsec_... value from create / rotate-secret.
wh = Webhook(secret)

@app.post("/cazvid-webhooks")
async def receive(request):
    raw = await request.body()  # verify the RAW bytes
    headers = {
        "webhook-id": request.headers["webhook-id"],
        "webhook-timestamp": request.headers["webhook-timestamp"],
        "webhook-signature": request.headers["webhook-signature"],
    }
    event = wh.verify(raw, headers)  # raises on an invalid signature
    return Response(status_code=200)

Verificación manual (sin dependencia)

import { createHmac, timingSafeEqual } from "node:crypto";

// Fallback if you cannot add the standardwebhooks dependency.
function verify(rawBody, headers, whsecret, toleranceSec = 300) {
  const id = headers["webhook-id"];
  const ts = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;

  // Strip "whsec_" and base64-decode to the raw signing key.
  const key = Buffer.from(whsecret.replace(/^whsec_/, ""), "base64");
  const signed = id + "." + ts + "." + rawBody;
  const expected = createHmac("sha256", key).update(signed).digest("base64");

  // The header can carry several space-delimited signatures during rotation.
  return headers["webhook-signature"]
    .split(" ")
    .map((part) => part.split(",")[1])
    .some((sig) => {
      const a = Buffer.from(sig);
      const b = Buffer.from(expected);
      return a.length === b.length && timingSafeEqual(a, b);
    });
}