Webhooks

Crea webhooks desde Dashboard → Desarrolladores → Webhooks o via API. Selecciona los eventos que quieres recibir y proporciona un endpoint HTTPS.

curl -X POST https://www.workflows.com.es/api/v1/webhooks \
  -H "Authorization: Bearer wf_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Alerts",
    "url": "https://my-server.com/webhooks/workflows",
    "events": ["alert.created", "alert.critical", "alert.resolved"]
  }'

Formato del payload

Cada delivery envía un POST con los siguientes headers y body:

Content-Type: application/json
X-WorkFlows-Signature: sha256=<hex digest>
X-WorkFlows-Event: alert.created

{
  "event": "alert.created",
  "orgId": "org_abc123",
  "timestamp": "2026-05-19T16:30:00.000Z",
  "data": {
    "id": "alert_xyz789",
    "title": "Inventario crítico: Materia Prima A",
    "severity": "critical",
    "status": "active",
    "projectId": "proj_def456",
    "area": "Inventario",
    "createdAt": "2026-05-19T16:30:00.000Z"
  }
}

Cada payload incluye una firma HMAC-SHA256 en el header X-WorkFlows-Signature. Siempre verifica la firma antes de procesar el payload para asegurar que proviene de WorkFlows.

import crypto from "crypto";

function verifySignature(payload, signature, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret)
      .update(payload)
      .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// En tu endpoint:
app.post("/webhooks/workflows", (req, res) => {
  const signature = req.headers["x-workflows-signature"];
  const isValid = verifySignature(
    JSON.stringify(req.body),
    signature,
    process.env.WORKFLOWS_WEBHOOK_SECRET
  );

  if (!isValid) return res.status(401).send("Invalid signature");

  // Procesar el evento...
  const { event, data } = req.body;
  console.log(`Evento recibido: ${event}`, data);

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

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

# En tu endpoint (Flask):
@app.route("/webhooks/workflows", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-WorkFlows-Signature", "")
    if not verify_signature(request.data, signature, WEBHOOK_SECRET):
        return "Invalid signature", 401

    event = request.json["event"]
    data = request.json["data"]
    # Procesar...
    return "OK", 200

Suscríbete solo a los eventos que necesitas. Cada webhook puede escuchar múltiples eventos.

Si tu endpoint no responde con un status 2xx en 10 segundos, WorkFlows reintentará con backoff exponencial hasta 5 intentos:

Después de 5 intentos fallidos, el delivery se marca como fallido. Puedes ver el historial de deliveries en Dashboard → Desarrolladores → Webhooks → Deliveries o via API con GET /api/v1/webhooks/{id}/deliveries.

Buenas prácticas

• Responde rápido — retorna 200 lo antes posible y procesa el evento de forma asíncrona.
• Verifica siempre la firma — no proceses payloads sin validar X-WorkFlows-Signature.
• Idempotencia — tu endpoint puede recibir el mismo evento más de una vez (reintentos). Usa el data.id para deduplicar.
• Usa HTTPS — WorkFlows solo envía webhooks a endpoints HTTPS por seguridad.