---
title: "Subscribe to webhook events for a Flow App"
method: POST
path: "/flow/apps/{appId}/subscriptions"
tags: ["Flow Webhooks"]
---

# Subscribe to webhook events for a Flow App

`POST /flow/apps/{appId}/subscriptions`

Creates a webhook subscription. Events matching `eventType` will be delivered
to `targetUrl` with HMAC-SHA256 signature validation using the provided `secret`.
The `targetUrl` must not resolve to a private/loopback IP (SSRF protection).

## Path parameters

- `appId` string, required

## Request body

- object
  - `eventType` string, required — Event type to subscribe to (e.g. "contact.requested", "step_submitted")
  - `targetUrl` string, uri, required — HTTPS URL to receive webhook deliveries (no private IPs)
  - `secret` string, required — Shared secret for HMAC-SHA256 signature verification

## Response `201`

Subscription created

- WebhookSubscription
  - `subscriptionId` string, required
  - `appId` string, required
  - `eventType` string, required
  - `targetUrl` string, uri, required
  - `createdAt` string, date-time, required

## Other responses

- `400` — Bad request (RFC 7807)
- `401` — Unauthorized (RFC 7807)
- `404` — Not found (RFC 7807)

---

[API](https://skmtc.net/overledger/apis/overledger-server.md) · [All operations](https://skmtc.net/overledger/apis/overledger-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/overledger/overledger-server/revisions/dd31e0a52064/schema)