Chapter 2: Bringing Data In

Triggering via Webhooks

Target Audience: Users setting up their triggers (Forms or Webhooks).

Webhooks are the backbone of automation in Strucsta. While our auto-generated UI forms are great for manual data entry, webhooks allow you to programmatically trigger document generation from any external system—whether that's a CRM like HubSpot, an automation tool like Zapier or n8n, or your own custom backend.

When you configure an Ingest step to use a Webhook source, Strucsta generates a unique endpoint for your workflow.

The Webhook Endpoint

To trigger a run, you need to send a standard HTTP POST request to your workflow's unique webhook URL. You can find this URL in the configuration panel of your Source step.

Endpoint Format:

POST [https://api.strucsta.com/webhook/](https://api.strucsta.com/webhook/)[trigger_id]
Content-Type: application/json

Structuring the Payload

The JSON payload you send to the webhook must map to the Expected Fields defined in your Ingest step's schema.

For example, if your Blueprint Engine defined an invoice workflow expecting a client's name, their tier, and an array of services, your payload should look exactly like this:

{
  "clientName": "Acme Corp",
  "subscriptionTier": "Enterprise",
  "services": [
    { "name": "Security Audit", "cost": 5000 },
    { "name": "Load Testing", "cost": 2500 }
  ]
}

Fail-Fast Validation

One of the most important features of Strucsta's ingest pipeline is Fail-Fast Validation.

Because AI reasoning and PDF rendering are computationally expensive operations, Strucsta acts as a strict gatekeeper at the Ingest step. When your webhook payload hits our servers, it is instantly validated against the JSON schema you defined in the workflow editor.

If the payload is valid: The system accepts the request (returns a 202 Accepted or 200 OK) and initiates the Run.
If the payload is invalid: (e.g., you sent a string where a number was expected, or missed a required field), the engine instantly rejects the request with a 400 Bad Request containing a detailed error message.

Why this matters: It prevents bad data from ever reaching the LLM, saving your AI credits and ensuring you never deliver a broken or incomplete PDF to a client.

Understanding Data Flow (Cumulative Context)

To design effective templates, you must understand how data moves from your webhook through the rest of the pipeline.

Strucsta is optimized for short, highly deterministic workflows. Because of this, data is treated as a Cumulative Context and is merged flatly as it moves from step to step.

Ingest Step: Your webhook payload arrives.

State: { "clientName": "Acme Corp" }

Reason Step: The AI processes the input and generates structured output (e.g., a personalized executive summary).

State Merges: The AI output is injected alongside the original data.
State: { "clientName": "Acme Corp", "executiveSummary": "Acme Corp requires a high-level security audit..." }

Render Step: The pdfmaker engine receives the entire flattened state.

When you write your JSONC templates, you don't need to worry about complex nested references or tracking which step produced which piece of data. You simply reference {{clientName}} and {{executiveSummary}} directly, knowing the engine has reliably accumulated the context for you.