---
title: "Add a webhook"
method: POST
path: "/api/v1/manage/forms/{form}/webhooks"
tags: ["Webhooks"]
---

# Add a webhook

`POST /api/v1/manage/forms/{form}/webhooks`

## Request

- Base URL: `https://fillo.so`
- URL: `https://fillo.so/api/v1/manage/forms/{form}/webhooks`
- Auth: HTTP bearer

Register a signed webhook with optional receiver authentication. The response includes the Fillo signing secret ONCE; neither it nor a receiver credential is retrievable again. Delivery URLs are SSRF-guarded and must be http(s). Scope: webhooks:manage.

## Path parameters

- `form` string, required

## Request body

- object
  - `url` string, uri, required: An http(s) delivery URL.
  - `includeAbandoned` boolean: Also deliver draft.abandoned events.
  - `authentication` WebhookAuthenticationInput: Optional authentication Fillo adds for the receiver. For bearer or x-api-key, secret is required, encrypted at rest, and never returned.
    - `type` 'none' | 'bearer' | 'x-api-key', required
    - `secret` string

## Response `201`

The created webhook, with its signing secret shown once.

- WebhookCreated
  - `id` string, required
  - `url` string, uri, required
  - `events` string[], required
  - `authentication` 'none' | 'bearer' | 'x-api-key', required: Configured receiver-authentication mode.
  - `secret` string, required: The HMAC signing secret. Shown once, never retrievable again.

## Other responses

- `400`: Invalid request (e.g. a body on a GET/DELETE, or a missing required query parameter).
- `401`: Missing, malformed, unknown, revoked, or expired key.
- `403`: The key is valid but lacks the required scope.
- `404`: No such resource in this project (returned instead of 403 for ids in other projects).
- `429`: Per-key (120/min), per-workspace (240/min), or per-IP (300/min) rate limit exceeded. Retry after the Retry-After header.

---

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