Setting up a webhook Surface

A Webhook Surface lets external systems push events into your Product over HTTP. When a service like Stripe, Shopify, or GitHub sends an event, the Surface verifies it, figures out which event type it is, and routes it to the right Capability — passing the event payload through to your Flow or Agent.

Before you begin, create a Product and decide which Capability should handle incoming events. You will also need access to the external service so you can register Runtype’s webhook URL and copy its signing secret.

Create the webhook Surface

1. Open the Product you want to receive events.
2. Go to Surfaces and click Add Surface.
3. Select Webhook.
4. Give the Surface a name and copy the webhook URL Runtype generates for it.
5. Register that URL in the external service’s webhook settings.

Teach the Surface your payload shape

A Webhook Surface needs to know the shape of the events it will receive so it can route them and map their fields. There are two ways to provide it:

• Paste a sample. If you already have an example event, paste a JSON payload, a JSON Schema, or an AsyncAPI document. Runtype detects the format and infers a schema from it.
• Listen and learn. Turn on listening mode and send a few test events from the external service. After three or more observations, Runtype proposes an inferred schema covering the fields it saw, marking which are always present and which are optional.

The Surface moves through these states as you set it up:

Review the proposed schema, then Confirm it to activate the Surface, or Reject to clear the observations and start listening again.

Verify webhook signatures

Most providers sign their webhooks so you can confirm an event genuinely came from them. In the Surface’s signing configuration, choose your provider and paste its signing secret. Runtype verifies every incoming event against the provider’s algorithm and rejects requests that fail.

Signature checks use constant-time comparison, and you can set a timestamp tolerance to reject replayed events. Use None only for trusted internal sources.

Route events to Capabilities

A single webhook endpoint often receives many event types. Event routing sends each type to the Capability that should handle it.

1. Set the event type path — the dot path to the field that names the event (for example, type for Stripe).
2. Add routes that map each event type to a Capability. Glob patterns like payment_intent.* match a family of events.
3. Optionally set a fallback Capability for events that match no route.

Map payload fields to Flow inputs

Runtype passes the complete event through to your Capability without rewriting it. The full request body is available as {{payload}}, so you can reference any field with a dot path — for example, {{payload.data.object.amount}}.

By default, top-level fields of the payload are also made available as Flow inputs by their own names, so {{customerId}} resolves when the payload has a customerId field. To map nested or differently named fields, define field mappings: set the Flow input name as the target and a dot path into the payload as the source.

amount     ← data.object.amount
customerId ← data.object.customer

When entering source paths, the editor suggests paths from the confirmed schema so you do not have to remember the structure.

Choose synchronous or asynchronous handling

• Asynchronous (default): Runtype acknowledges the event immediately and runs the Capability in the background. Best for most integrations.
• Synchronous: the caller waits for the Capability to finish and receives its result. Useful for validation webhooks that expect a response.

Some providers inspect the response body rather than the status code. For those, a Surface can return a fixed response — for example, empty TwiML with an application/xml content type for Twilio, or a 204 with no content for Shopify.

Test the connection

1. Send a test event from the external service, or use its dashboard’s “send test webhook” feature.
2. Confirm the event reaches your Product and routes to the expected Capability.
3. Check the execution in Logs to see the payload your Flow received.

If an event later diverges from the confirmed schema, the Surface enters the drift-detected state so you can review the change and re-confirm.

Next steps

• To understand how Surfaces fit into a Product, read What are Surfaces?.
• To attach the Capability that handles events, see Adding Capabilities to a Product.
• To route requests when the Surface exposes more than one Capability, see Surface orchestration modes.
• To inspect what your Flow received, see Working with logs.