Update Webhook Triggers: Add Async and Sync

docs/build/triggers.md

@@ -25,6 +25,92 @@ Trigger by adding authentication, head over to our
 Learn how a workflow's initial `state` gets built from a webhook trigger
 [here](../jobs/state#webhook-triggered-runs).
 
+## **Webhook Trigger Responses**
+
+When a workflow is triggered via a webhook, OpenFn can run that workflow in one
+of two ways, depending on how the trigger is configured and what the calling
+system needs.
+
+### **Asynchronous mode**
+
+By default, workflows are executed **asynchronously**.
+
+This means OpenFn sends an HTTP response **immediately after receiving the
+webhook request**, once the Work Order and Run have been created.
+
+**Use this mode when:**
+
+- The calling system only needs confirmation that the request was received
+- You want fast responses and minimal coupling
+- The calling system does not need the result of the workflow run (or expects
+  knowledge of the result to be delivered to another endpoint)
+
+**When the response is sent:**
+
+Immediately, during the same HTTP request that triggered the workflow.
+
+**What this response represents:**
+
+It confirms that OpenFn has accepted the request and scheduled the workflow to
+run. It does **not** include the workflow’s output.
+
+#### The async-mode response
+
+- Status code: `200`
+- Body:
+  ```json
+  {
+    "work_order_id": "abc123",
+    "run_id": "xyz456"
+  }
+  ```
+
+### **Synchronous response (after completion)**
+
+Workflows triggered by webhooks can also be configured to respond
+**synchronously**, after the workflow has finished running.
+
+In this mode, OpenFn sends a response **after the run finishes**, returning its
+final status (e.g., success, failed, killed) and state.
+
+**Use this mode when:**
+
+- The calling system needs the result of the workflow
+- You need to know whether the run succeeded or failed
+- You want access to the workflow’s final output
+
+**When the response is sent:**
+
+After the workflow completes, not during the original webhook request.
+
+**What this response includes:**
+
+- The final output of the workflow
+- Metadata describing the run and its outcome
+
+#### The sync-mode response
+
+- Status code: `201`
+- Body:
+  ```json
+
+    {
+    "data": {
+      "...final": "run state goes here..."
+    },
+    "meta": {
+      "work_order_id": "abc123",
+      "run_id": "xyz456",
+      "state": "success",
+      "error_type": null,
+      "inserted_at": "2025-10-23T10:15:00Z",
+      "started_at": "2025-10-23T10:15:05Z",
+      "claimed_at": "2025-10-23T10:15:06Z",
+      "finished_at": "2025-10-23T10:15:20Z"
+    }
+  }
+  ```
+
 ## Cron Triggers (formerly timers)
 
 **Cron Triggers** run Workflows based on a cron schedule, and are good for