---
title: "Subscribe to an event"
method: POST
path: "/api/v1.1/webhooks"
tags: ["Webhooks"]
---

# Subscribe to an event

`POST /api/v1.1/webhooks`

## Request

- Base URL: `https://app.formaportal.com`
- URL: `https://app.formaportal.com/api/v1.1/webhooks`
- Auth: OAuth 2 (authorization code, authorization URL `https://app.formaportal.com/oauth/authorize`, token URL `https://app.formaportal.com/api/oauth/token`, scopes: `webhooks:write`)

Start receiving an event for one portal. `portalId` is required — a
connection covers several portals, so a subscription has to say which.

Re-subscribing the same URL for the same portal and event is idempotent, so a
retried call does not double-deliver. The same URL for a **different** portal
is a separate subscription, which is how one integration listens to several
portals.

`targetUrl` must be a public HTTPS URL. Anything resolving to a loopback,
private, link-local or CGNAT address is refused, here and again at delivery.

## Request body

- object
  - `portalId` string, required: A portal from GET /api/v1.1/portals.
  - `event` 'form_submission' | 'contact_registered', required
  - `targetUrl` string, uri, required: Where to POST the event. `hookUrl` and `target_url` are accepted as aliases.

## Response `201`

The subscription.

- WebhookSubscription
  - `id` string, required
  - `portalId` string: The portal this subscription listens to. Absent on v1, which had only one.
  - `event` 'form_submission' | 'contact_registered', required
  - `targetUrl` string, uri, required

## Other responses

- `400`: Missing field, unknown event, or an unusable targetUrl.
- `401`: Missing, invalid, expired or revoked token. The `WWW-Authenticate` header points at the protected-resource metadata.
- `403`: The token lacks `webhooks:write`, or this connection does not cover that portal.

---

[API](https://skmtc.dev/formaportal/apis/formaportal-api.md) · [All operations](https://skmtc.dev/formaportal/apis/formaportal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/formaportal/apis/formaportal-api/revisions/a9412c3b13cb?raw)