Outbound Webhooks

Creating a Webhook

Register a webhook via the API. The response includes a secretfor signature verification — store it securely, it is only shown once.

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

{
  "data": {
    "id": "whk_abc123",
    "name": "Slack Notifications",
    "url": "https://your-server.com/webhooks/workflows",
    "events": ["alert.created", "alert.critical", "csv.uploaded"],
    "isActive": true,
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "createdAt": "2026-05-19T12:00:00.000Z"
  }
}

Requirements: URL must be HTTPS and must not target private/internal addresses (SSRF protection). Name max 100 chars.

Payload Format

Each webhook delivery is a POST request with these headers and a JSON body:

{
  "event": "alert.created",
  "orgId": "org_abc123",
  "timestamp": "2026-05-19T12:05:00.000Z",
  "data": {
    "id": "alt_xyz789",
    "title": "Low inventory: Raw Material A",
    "severity": "critical",
    "projectId": "proj_abc123",
    "area": "Inventory",
    "value": "45 units",
    "threshold": "100 units"
  }
}

Signature Verification

Every delivery includes an X-WorkFlows-Signature header in the format sha256=<hex-digest>. Verify it by computing HMAC-SHA256 of the raw request body using your webhook secret:

import crypto from "crypto";

function verifySignature(body, secret, signature) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature),
  );
}

// In your webhook handler:
const rawBody = await req.text();
const sig = req.headers.get("x-workflows-signature");
if (!verifySignature(rawBody, process.env.WEBHOOK_SECRET, sig)) {
  return new Response("Invalid signature", { status: 401 });
}

import hmac
import hashlib

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

# In your webhook handler:
raw_body = request.get_data()
sig = request.headers.get("X-WorkFlows-Signature", "")
if not verify_signature(raw_body, WEBHOOK_SECRET, sig):
    abort(401, "Invalid signature")

Available Events

WorkFlows supports 30 webhook events across 6 categories. Subscribe only to the events you need.

Best Practices

• 1.Respond quickly. Return a 2xx status within 10 seconds. Process the payload asynchronously if needed.
• 2.Always verify signatures. Never trust payloads without checking the HMAC signature.
• 3.Handle duplicates. Use the timestamp and event data to deduplicate in case of retries.
• 4.Use HTTPS only. Webhook URLs must use HTTPS. HTTP endpoints are rejected.
• 5.Subscribe selectively. Only listen to events you need to reduce noise and processing overhead.