---
id: types-connect-an-app
title: "Connect an app"
summary: "Give another application everything it needs to call a flow through a webhook, or to receive the webhooks a flow sends - payload, signed client or receiver code in C#, Python, Go, Java and PHP, OpenAPI 3.1 and ready-to-run test commands."
audience: user
keywords: "connect an app, webhook, webhook receiver, webhook sender, client code, receiver code, openapi, try it, curl, powershell, signature, hmac, contract hash, rest handler, swagger"
---
# 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](/documentation/plugins/web/webhook-receiver) or a [Webhook sender](/documentation/plugins/web/webhook-sender):
double-click the component, or click the `{}` button next to its language field in the properties.

## A flow that receives webhooks

```text
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](/documentation/plugins/web/http-listener-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

```text
... 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](/documentation/plugins/web/rest-api-listener). 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.