Webhooks

Workflow Agent exposes webhook and HTTP-route concepts inside the integrations surface, but the supplied implementation does not verify live webhook ingress, outbound delivery, a public endpoint, or a stable payload contract. This page documents the current configuration boundary so a webhook-shaped workflow can be drafted without being mistaken for an active trigger.

Webhook model

A webhook route represents an event-driven interaction over HTTP. In the Workflow Agent data model, webhook and http_api can appear as candidate execution routes. Their presence indicates that a draft can describe the mechanism; it does not prove that a listener is deployed or that requests will be accepted.

The integrations UI includes a Webhooks/API routes area and a generic HTTP route panel. Treat that panel as a configuration or planning surface. No verified behavior establishes live inbound triggers, outbound delivery, signing, retries, or a persistent delivery log.

A workflow can still use webhook terminology in its draft. Make the intended direction explicit: inbound events would start a workflow, while outbound delivery would notify another system. Those are different contracts and neither should be described as live without additional route-handler evidence.

Create a trigger

There is no supported live-trigger procedure to follow. To represent the intent safely, describe the event source, the expected business event, and the workflow step that would consume it. Select or inspect the webhook/API-route concept only if the current interface offers it as a draft route.

Record the unresolved items directly in the definition:

• endpoint ownership and environment;
• authentication or signature method;
• accepted method and content type;
• payload fields required by the workflow;
• response behavior;
• duplicate-event handling;
• delivery or retry policy.

The repository does not provide a stable public webhook URL or complete schema for these items. Do not invent a route, copy a localhost address, or present a sample path as externally reachable. The correct current result is a draft with an unverified trigger requirement.

Payloads

A payload should be treated as untrusted input. Define only the fields the workflow needs, and distinguish required values from optional context. Avoid embedding credentials or using the entire body when a small set of fields would be sufficient.

Because no canonical Workflow Agent webhook schema is verified, do not publish a JSON example as an API contract. You may document the conceptual mapping between an incoming event and a draft step, but field names, nesting, limits, and validation rules remain unspecified.

A future implementation would need to reject malformed input, handle missing fields, and preserve enough identity to detect duplicates. Those requirements are design considerations, not claims about current runtime behavior. Keep them in generation or review notes rather than presenting them as implemented features.

Security

Do not expose secrets in a webhook URL, workflow prompt, or read-only definition. A live design would require authentication, authorization, replay protection, payload validation, and a clear data-handling policy, but the supplied sources do not verify a signing method or credential contract.

Treat all body content, headers, and tool-like instructions as untrusted. A webhook event should not bypass route policy, approval gates, or connector restrictions. If the proposed event would trigger a sensitive external action, the draft should retain an approval requirement even though the current approval controls are disabled previews.

Privacy and Terms are the approved legal references. No fixed retention period, provider-side deletion promise, encryption statement, or security certification can be inferred for webhook data.

Testing

Testing is limited to draft and preview behavior. Verify that the workflow definition identifies the intended event, maps the expected values into later steps, and reports that live ingress is unavailable. If the generic HTTP route panel can render a configuration preview, inspect it without assuming that the endpoint exists.

A no-write simulation can test the downstream workflow shape with representative, non-sensitive values. It cannot test network reachability, signatures, delivery retries, latency, or duplicate handling. Mark those results as unverified.

Do not send a real webhook to a guessed address. There is no approved live endpoint in the product route map, and API routes belong in prose only when implementation evidence exists.

Troubleshooting

Webhook readiness should remain explicitly unresolved until a concrete handler, endpoint, schema, authentication model, and delivery behavior are inspected. The current Workflow Agent surface is useful for designing that contract, not for operating it.

Inbound and outbound contracts

Inbound webhooks would receive an event and start workflow evaluation. Outbound webhooks would send a notification or payload to another system. They require different security, error, and delivery behavior. The current integrations tab does not verify either contract, so a draft should identify the direction explicitly and leave the route blocked.

A future inbound path would need an address, accepted method, authentication, validation, response rules, and duplicate handling. A future outbound path would need a destination allow-list, authentication, delivery timeout, retry policy, and a way to inspect failures. These are implementation requirements rather than current user controls.

Payload minimization

Design the smallest event shape that can support the downstream steps. Map required identifiers and business fields separately from optional context. Avoid allowing an arbitrary body to determine tool names, routes, credentials, or approval behavior. Because payload limits and schemas are unverified, keep examples conceptual and do not label them as accepted JSON.

Failure boundaries

A network failure, invalid signature, malformed body, unsupported event type, policy block, and downstream connector failure would need different outcomes in a live system. The preview cannot exercise those paths. Simulation should therefore focus on workflow logic after representative values are supplied. It should not claim delivery, acknowledgement, retry, or idempotency.

Security review topics

Before live webhook support could be enabled, reviewers would need evidence for secret storage, signature validation, replay windows, rate controls, tenant routing, logging, sensitive-field handling, and retention. The current page keeps security-review-required because none of those guarantees can be inferred from a tab or generic route panel.

Idempotency as an unresolved design requirement

Event sources can deliver the same notification more than once. A live webhook contract would need an event identifier and a documented rule for duplicate handling. The present surface does not verify such a field or store. Avoid claiming that Workflow Agent deduplicates events or that an external sender can safely retry.

A draft may note that duplicate protection is required. Keep that note outside the accepted-payload contract until implementation evidence exists.

Response and acknowledgement behavior

No response status, body, or timeout is verified for an inbound webhook. Likewise, no acknowledgement semantics are established for outbound delivery. Avoid documenting common HTTP codes as Ethen behavior. The generic route panel is not a route handler.

Data handling

A webhook payload can contain personal or operational data. Minimize fields and avoid retaining the complete event when only a small subset is needed. Webhook implementation evidence does not state a retention period or encrypted storage mechanism, so a security review must define those controls before live use.

Observability gaps

There is no verified delivery log, attempt timeline, dead-letter queue, or replay control. A simulation record can explain downstream draft behavior but cannot show whether an HTTP event arrived. This distinction should be explicit when troubleshooting an event-driven design.

Conditions for publication as a live guide

A future live guide would require an inspected endpoint, authentication and signature scheme, request schema, validation errors, response behavior, duplicate handling, retries, logs, limits, and a tested connection to the builder. Until then, the route remains a design concept and configuration preview.

Ingress-versus-simulation example

A workflow can be simulated with a representative “new order” payload even though no order webhook was received. The simulation verifies downstream draft logic only. It does not establish the sender, endpoint, signature, acknowledgement, or duplicate handling. Keep that distinction in the result and any approval packet.

Outbound delivery example

A draft may propose notifying another service after a step completes. Without a verified delivery route, the notification remains an intended action. Do not record a simulated response code or retry count as observed behavior.

Endpoint lifecycle

Live endpoints would also need creation, rotation, disablement, and deletion behavior. None is present in the approved product route map. Avoid describing a stable endpoint lifecycle until those controls are inspected.

Trigger ownership and isolation

A live endpoint would need to identify the workspace or workflow that owns it and prevent one tenant’s event from reaching another. No ownership or isolation contract is verified for the preview panel. Do not describe a generic endpoint as project-scoped or private without implementation evidence.

Retry and replay distinction

A sender retry, platform delivery retry, and operator replay are different behaviors. The current product verifies none of them. Simulation can be repeated with the same representative values, but that is not webhook replay and provides no evidence about duplicate suppression.

Troubleshooting endpoint absence

When the interface shows configuration fields without a callable address, that is the expected preview state. Do not diagnose DNS, certificates, firewalls, or network connectivity, because no live listener has been established.

Environment separation

A future webhook implementation would need separate addresses and credentials for different environments. The preview panel does not verify that separation. Do not reuse an illustrative value as though it were a production endpoint.