Connect an app

When another application needs to send events to a flow, or receive them from one, Connect an app gives its developers everything in one place: the URL and security, the payload with a sample, generated client or receiving code in their language, an OpenAPI document and test commands they can run straight away.

It opens from a Webhook receiver or a Webhook sender: double-click the component, or click the {} button next to its language field in the properties.

A flow that receives webhooks

Http listener → Webhook receiver → Json deserializer → ... your logic

The Http listener owns the URL, port and TLS. The Webhook receiver checks the signature, drops repeated deliveries and answers the sender. The Json deserializer turns the body into your payload type; that type is what the generated client sends.

For a receiver, the dialog gives the developers of the calling application:

Page	Contents
Overview	Method and URL, the signature scheme and its headers, how the secret is set (never the secret itself), the status codes and the behaviour.
Payload	Every field of the payload type with type, required, nullable, default and description, a sample JSON message, and the contract hash.
Code	A client in C#, Python, Go, Java or PHP, plus OpenAPI (YAML) / OpenAPI (JSON) and the JSON Schema of the payload.
Try it	A curl (bash) and a PowerShell command that send a correctly signed test message.

The generated client signs every request the way the receiver checks it, retries network errors, timeouts, 408, 429 and 5xx with the same event id (three attempts with growing delay), and sends the contract hash so the flow can detect an outdated payload type. It reads the secret from the VIADUCTA_WEBHOOK_SECRET environment variable or takes it in its constructor.

Getting the flow's answer

By default the receiver answers the sender as soon as the request is accepted, then runs the flow (AckMode Immediate): senders get a fast answer. Set AckMode to AfterFlow and end the flow with an Http response when the caller needs the flow's result: the generated clients return that answer to the calling code (Delivery.ResponseBody in C#, response_body in Python).

A flow that sends webhooks

... your logic → Webhook sender → https://partner.example.com/webhooks/order-created

For a sender, the dialog gives the developers of the receiving application the same four pages, with receiving code instead of a client: a signature verifier and a ready endpoint on port 8000, in

• C#: an ASP.NET Core minimal API,
• Python: the standard library's http.server, with a FastAPI example,
• Go: a net/http handler,
• Java: the JDK's HTTP server, with a Spring controller example,
• PHP: a plain script, with a Laravel route example.

The endpoint answers 200, 401 for a bad signature, 400 for a payload it can't read and 500 when the application's handler fails. Every delivery has an event id; the receiving application uses it to drop repeats.

Security

Receivers support HMAC signatures in a header, the GitHub, Stripe, Slack and Standard Webhooks schemes, a shared secret header, and Microsoft Graph notifications. Keep the secret in an expression setting (=Secrets.OrderWebhook) so each environment has its own, and use the secondary secret while you rotate it. The Try it commands read the secret from VIADUCTA_WEBHOOK_SECRET; set it first.

REST APIs

For request-response APIs, use the Rest handler. Its Rest API Builder dialog has an OpenAPI page with the OpenAPI 3.1 document of every Rest handler in the flow, and a Try it page with curl and PowerShell commands. The running flow also serves the document at swagger.json, so API tools and gateways can read it directly.