# Ikiform documentation

> The complete Ikiform docs as markdown, generated from the same source as https://ikiform.com/docs.

---

Source: https://ikiform.com/docs

# Quickstart

> Point any HTML form at Ikiform and receive your first submission in two minutes.

Ikiform is the backend for every form. You keep your own markup, framework and styles. Point the form at an Ikiform endpoint and Ikiform validates each post, filters spam, stores it in your workspace, emails you and delivers it to your systems by signed webhook.

Code samples in these docs use the sample form id `frm_xxxxxxxxxxxxxxxx`. Replace it with your own form's id, which you find on the form's overview in the dashboard.

## Pick how you send

Every form gets one public endpoint, `https://ikiform.com/f/<formId>`. Anything that can send an HTTP POST can use it.

| You send from | Use | Guide |
| --- | --- | --- |
| A plain HTML page or a site builder | `<form action>` | [HTML forms](https://ikiform.com/docs/html.md) |
| React, Next.js, Vue, Svelte, Astro | `fetch` or `submit` from the SDK | [Guides](https://ikiform.com/docs/guides/nextjs.md) |
| A backend, script or integration | JSON over HTTPS with a secret key | [From a server](https://ikiform.com/docs/guides/server.md) |
| A shadcn/ui project | The registry component | [shadcn/ui component](https://ikiform.com/docs/shadcn.md) |

## Quickstart

### Step 1: Create a form

Sign in to the [dashboard](https://ikiform.com/dashboard), create a workspace and add a form. Its overview shows the endpoint URL and ready-made snippets for HTML, JavaScript and React.

### Step 2: Point your form at the endpoint

Set the form's `action` to the endpoint and `method` to `post`. Every input with a `name` becomes a field of the submission.

`contact.html`:

```html
<form action="https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx" method="post">
  <input name="name" required />
  <input name="email" type="email" required />
  <textarea name="message"></textarea>
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
  <button>Send</button>
</form>
```

The hidden `_gotcha` input is a honeypot. People never see it; bots that fill it in are stored as spam. See [Spam protection](https://ikiform.com/docs/spam.md#honeypot).

### Step 3: Submit it

Open the page and send the form. The browser lands on Ikiform's thank-you page, or on your own page if you set a redirect. You can also post JSON from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello"}'
```

A JSON request gets a JSON answer with status `201`:

`201 Created`:

```json
{ "ok": true, "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3" }
```

### Step 4: See it arrive

The submission shows up in the dashboard right away. From there, add a [webhook](https://ikiform.com/docs/webhooks.md) to send each one to your app, or read them with the [REST API](https://ikiform.com/docs/api.md).

## Try it

The interactive request builder on this page composes a submission from field rows and shows the matching curl, fetch and SDK code. With the sample form id it only shows code; with your own form id it can send one real POST to `https://ikiform.com/f/<formId>` and print the status and JSON response. The request it builds looks like this:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello"}'
```

## Next steps

- [How it works](https://ikiform.com/docs/how-it-works.md) walks through every check a post goes through.
- [Define fields](https://ikiform.com/docs/fields.md) so Ikiform rejects bad data with clear field errors.
- [Turn on a human check](https://ikiform.com/docs/spam.md#human-check) and restrict the form to your domains.
- [Verify webhook signatures](https://ikiform.com/docs/webhooks.md#verify) in your backend.

---

Source: https://ikiform.com/docs/how-it-works

# How it works

> Every check a submission goes through, in order, and what each one can return.

Each post to `/f/<formId>` runs through the same pipeline. Cheap checks run first, so a flood or an unknown form costs almost nothing. The first check that fails decides the response.

The pipeline, in order:

1. IP flood guard: at most 600 posts a minute from one IP across every form, before the form is looked up. Fails with `429 rate_limited`.
2. Form lookup: unknown, deleted and disabled forms fail with `404 not_found`.
3. Form rate limits: the form's preset, counted per visitor IP and per form. Fails with `429 rate_limited`.
4. Paused forms fail with `403 form_paused`.
5. Body parsing: urlencoded, multipart or JSON, at most 256 KB. Fails with `415`, `400 invalid_body`, `413 payload_too_large`, `422 too_deep` or `422 files_not_supported`.
6. API key, when an `Authorization` header is sent. Fails with `403 forbidden` or `403 origin_not_allowed`.
7. Allowed domains: a post from another site is stored as spam, or fails with `403 origin_not_allowed`.
8. Human check: fails with `403 challenge_required` or `403 captcha_failed`. Browser form posts get a check page instead.
9. Field validation: fails with `422 validation_failed`.
10. Spam scoring: a score of 5 or more is stored as spam but still answered as a success.
11. Idempotency: a repeated key replays the first response, or fails with `409` or `422`.
12. Monthly usage: far over the limit fails with `429 quota_exceeded`.
13. Store: `201` with the submission id, or a `303` redirect for browser posts. Webhooks, notification emails and the live dashboard update follow.

## What each stage does

### Rate limits before anything else

Rate limits run before the body is read. The flood guard (600 a minute per IP) runs even before the form lookup, so a flood never reaches the database. The form's own rules run right after the lookup. Rejected requests don't use up the allowance. Exact numbers are on [Rate limits](https://ikiform.com/docs/rate-limits.md).

### Parsing

The body is parsed as urlencoded, multipart or JSON. Text is decoded as UTF-8, normalized to NFC, CRLF becomes LF and control characters are removed. Names that start with `_` are reserved instructions, such as `_redirect` and `_subject`, and are never stored as answers. See [HTML forms](https://ikiform.com/docs/html.md#reserved-fields).

### Who sent it

An `Authorization: Bearer` header is optional. A secret key (`ik_sk_`) with the `submissions:write` scope skips the allowed-domains check and the Ikiform human check. A publishable key (`ik_pub_`) only works from the domains listed on the key. Without a key, the post is judged by its `Origin`.

### Spam

Spam is never an error. A post that fails the allowed-domains policy in spam mode, or scores 5 or more, is stored with status `spam` and gets the same success response as a real one, so bots learn nothing. Spam sends no webhooks or emails and doesn't count toward usage. See [Spam protection](https://ikiform.com/docs/spam.md).

### Store and deliver

The submission, its webhook deliveries and its notification email are written in one database batch, then handed to a queue. Webhook delivery and email never slow down the response, and a submission is never stored without its deliveries.

## JSON or a redirect

The same endpoint answers browsers with pages and code with JSON. Ikiform decides per request:

| Request | Answer |
| --- | --- |
| `Accept` includes `application/json` | JSON |
| The body is JSON | JSON |
| `Sec-Fetch-Mode: navigate` (a normal form post) | Redirect or hosted page |
| Any other `Sec-Fetch-Mode`, such as `cors` from `fetch` | JSON |
| No `Sec-Fetch-Mode`, and `Accept` includes `text/html` | Redirect or hosted page |
| Anything else, such as curl | JSON |

In JSON mode success is `201 { "ok": true, "id": "sub_..." }`. In page mode success is a `303` redirect, and errors render a hosted error page that lists field problems by label.

## After a submission is stored

| What | When | Details |
| --- | --- | --- |
| Webhooks | Seconds later, retried for about 3 days | [Webhooks](https://ikiform.com/docs/webhooks.md) |
| Notification email | Seconds later, if notifications are on for the form | Capped at 50 emails per form per hour (10 for workspaces younger than 7 days), then one hourly digest |
| Dashboard | Immediately, live | Spam shows under the spam filter |
| REST API | Immediately | [REST API](https://ikiform.com/docs/api.md) |

> Forms whose submissions contain password, card or seed-phrase style field names are flagged and their notification emails held for review. Don't collect credentials with a form backend.

## Ids

| Id | Looks like | Notes |
| --- | --- | --- |
| Form | `frm_xxxxxxxxxxxxxxxx` | `frm_` plus 16 random characters. Public: it is in your form's action URL. |
| Submission | `sub_01k7v2c9t3e8m5q4x6z0a1b2c3` | `sub_` plus 26 characters, ordered by time. |
| Webhook delivery | `dlv_...` | Sent as `webhook-id`; stays the same across retries. |
| Request | `req_...` | Every response has an `X-Request-Id` header. Quote it when you contact support. |

**201** (`JSON success`)

```json
{ "ok": true, "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3" }
```

**303** (`Browser success`)

```http
HTTP/1.1 303 See Other
Location: https://example.com/thanks
X-Request-Id: req_01k7v2c9t3e8m5q4x6z0a1b2c3
```

---

Source: https://ikiform.com/docs/html

# HTML forms

> Post any HTML form to Ikiform with no JavaScript: redirects, reserved fields, arrays and the honeypot.

A plain HTML form is the whole integration. No script, no iframe and no embed: set the `action` to your form's endpoint and keep your own markup and CSS. This also works in site builders that let you paste custom HTML; see [Site builders](https://ikiform.com/docs/guides/site-builders.md).

## A basic form

`contact.html`:

```html
<form action="https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx" method="post">
  <label>
    Name
    <input name="name" autocomplete="name" required />
  </label>
  <label>
    Email
    <input name="email" type="email" autocomplete="email" required />
  </label>
  <label>
    Message
    <textarea name="message" rows="5"></textarea>
  </label>
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
  <button>Send</button>
</form>
```

- `method` must be `post`. The browser sends `application/x-www-form-urlencoded`, or `multipart/form-data` if you set `enctype`. Both work.
- Every control with a `name` becomes a field. Controls without a name, and disabled controls, are not sent by the browser.
- Values are stored as UTF-8 text, normalized to NFC, with CRLF line endings turned into LF and control characters removed.
- Browser validation such as `required` and `type="email"` helps people, but it is not a security check. Define [fields](https://ikiform.com/docs/fields.md) to have Ikiform enforce rules on the server.

## After submit

A successful browser post is answered with a `303` redirect. Ikiform picks the target in this order:

1. The form's **Redirect after submit** setting in the dashboard. Any `http:` or `https:` URL works here, because only workspace members can set it.
2. A `_redirect` (or `_next`) field in the post, if it passes the rules below.
3. Otherwise Ikiform's hosted thank-you page at `/f/<formId>/thanks`. When the form has allowed domains and the post came from an `https:` page on one of them, the page links back to it.

### Rules for _redirect

A `_redirect` value comes from the visitor's browser, so Ikiform only follows it when it is an `https:` URL with no username, password or custom port, on one of the form's allowed domains or a subdomain of one. Forms without allowed domains ignore `_redirect` entirely. With allowed domains set to `example.com`:

| _redirect | Followed | Why |
| --- | --- | --- |
| `https://example.com/thanks` | Yes | Allowed domain |
| `https://app.example.com/done` | Yes | Subdomain of an allowed domain |
| `http://example.com/thanks` | No | Not `https:` |
| `https://example.com:8443/thanks` | No | Custom port |
| `https://user@example.com/` | No | Contains a username |
| `https://example.com.evil.dev/` | No | Not the domain or a subdomain of it |

A `_redirect` that isn't followed falls through to the hosted thank-you page; it never causes an error. JSON requests ignore redirects and get `201` with the submission id.

### When a post is rejected

If a post is rejected, for example because a required field is missing, the browser sees a hosted error page with the HTTP status of the error. It lists the problems by field label and links back to the form. See [Errors](https://ikiform.com/docs/errors.md) for every code.

## Field names and arrays

Repeated names and names ending in `[]` become arrays. Use `[]` for checkbox groups and `<select multiple>` so that a single choice is still stored as an array.

`fields.html`:

```html
<fieldset>
  <legend>Topics</legend>
  <label><input type="checkbox" name="topics[]" value="billing" /> Billing</label>
  <label><input type="checkbox" name="topics[]" value="api" /> API</label>
</fieldset>

<select name="plan">
  <option value="starter">Starter</option>
  <option value="team">Team</option>
</select>

<label><input type="checkbox" name="newsletter" /> Send me product news</label>
```

Checking both topics and the newsletter box stores:

`Stored fields`:

```json
{
  "topics": ["billing", "api"],
  "plan": "team",
  "newsletter": "on"
}
```

- Names in brackets such as `address[city]` are kept literally; they are not turned into nested objects. Post JSON if you want nested values.
- An unchecked checkbox is not sent at all. With a `checkbox` [field](https://ikiform.com/docs/fields.md#types) defined, a missing box is stored as `false` and a checked one as `true`.
- A submission can have up to 100 fields, names up to 128 characters and values up to 16 KB. See [Limits](https://ikiform.com/docs/limits.md).

> File uploads are not built yet. An empty file input is ignored; a post that contains a real file is refused with `422 files_not_supported`.

## Reserved fields

Names that start with `_` are instructions for Ikiform. They are never stored as answers.

| Field | Effect |
| --- | --- |
| `_gotcha` | Honeypot. Leave it empty and hidden; a filled-in value adds 5 to the spam score, which is enough to store the post as spam. The name can be changed per form. |
| `_redirect`, `_next` | Where to send the browser after a successful post. See [Rules for _redirect](#redirect-rules). |
| `_subject` | Subject for notification emails. Whitespace is collapsed and it is cut to 200 characters. |
| `_replyto` | Reply-to address for notification emails. Ignored unless it is one valid email address. |
| `_idempotency` | Idempotency key, the same as the `Idempotency-Key` header. See [Idempotency](https://ikiform.com/docs/frameworks.md#idempotency). |
| `_ikiform_ts` | Signed render time, set by the SDK and the shadcn/ui component. A post sent under 2 seconds after render scores as spam. |
| `cf-turnstile-response` | The Turnstile token, added by the Turnstile widget or the SDK. |
| `_ikiform_via` | Set by Ikiform's own human check page. Don't send it yourself. |

Any other field starting with `_` is also dropped, so you can use names like `_source` for your own hidden markers without storing them.

`demo.html`:

```html
<form action="https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx" method="post">
  <input name="email" type="email" required />
  <input type="hidden" name="_subject" value="New demo request" />
  <input type="hidden" name="_redirect" value="https://example.com/thanks" />
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
  <button>Request a demo</button>
</form>
```

## The honeypot

The default honeypot name is `_gotcha`. You can change it per form under **Honeypot field** in the form's settings; whatever name you pick is treated as reserved and never stored. A plain `hidden` attribute is enough for most bots. If you see spam getting through, hide the input off-screen instead, because some bots skip inputs marked `hidden`:

`honeypot.html`:

```html
<div aria-hidden="true" style="position:absolute;left:-10000px;width:1px;height:1px;overflow:hidden">
  <label>
    Leave this empty
    <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" />
  </label>
</div>
```

Keep `tabindex="-1"` and `autocomplete="off"` so keyboard users and password managers never fill it in.

## Adding a human check

Forms with the spam check set to **Ikiform** need no change in your HTML. When a browser posts without a token, Ikiform answers with a short "Checking you're human" page on ikiform.com. It runs Cloudflare Turnstile, then posts the original fields again with the token. Your visitor ends on the same thank-you page as before. See [Spam protection](https://ikiform.com/docs/spam.md#human-check) for the full flow.

### With your own Turnstile keys

If the form uses **Your own Turnstile keys**, render the widget yourself. It adds the `cf-turnstile-response` field to the post. Posts without a valid token are rejected with `403 captcha_failed`.

`turnstile.html`:

```html
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<form action="https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx" method="post">
  <input name="email" type="email" required />
  <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
  <button>Send</button>
</form>
```

---

Source: https://ikiform.com/docs/frameworks

# JavaScript and fetch

> The submission endpoint in detail: body formats, headers, CORS, responses and idempotency.

Any code that can send an HTTP request can submit to Ikiform. Post JSON, `FormData` or urlencoded data to `https://ikiform.com/f/<formId>` and read a JSON answer. The [SDK](https://ikiform.com/docs/sdk.md) wraps this in one function, but it is optional. For framework walkthroughs, see the guides for [Next.js](https://ikiform.com/docs/guides/nextjs.md), [React](https://ikiform.com/docs/guides/react.md), [Vue](https://ikiform.com/docs/guides/vue.md), [Svelte](https://ikiform.com/docs/guides/svelte.md) and [Astro](https://ikiform.com/docs/guides/astro.md).

## With fetch

**JSON** (`submit.js`)

```js
const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
  method: "POST",
  headers: { "Content-Type": "application/json", Accept: "application/json" },
  body: JSON.stringify({
    name: "Ada Lovelace",
    email: "ada@example.com",
    message: "Hello",
  }),
});

const result = await response.json();
if (!result.ok) console.error(result.error.code, result.error.fields);
```

**FormData** (`form.js`)

```js
const form = document.querySelector("form");

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  const response = await fetch(form.action, {
    method: "POST",
    headers: { Accept: "application/json" },
    body: new FormData(form),
  });
  const result = await response.json();
  if (result.ok) form.replaceWith("Thanks, we got it.");
});
```

**SDK** (`submit.ts`)

```ts
import { submit } from "@ikiform/sdk";

const result = await submit("frm_xxxxxxxxxxxxxxxx", {
  name: "Ada Lovelace",
  email: "ada@example.com",
});

if (result.ok) console.log("Stored", result.id);
else console.error(result.error.code, result.error.fields);
```

## Try it

The interactive request builder composes a submission from field rows, shows the curl, fetch and SDK code for it, and can send one real POST when you enter your own form id. Nothing is sent automatically.

## Endpoints

| Method | Path | What it does |
| --- | --- | --- |
| `POST` | `/f/<formId>` | Create a submission |
| `OPTIONS` | `/f/<formId>` | CORS preflight, always `204` |
| `GET` | `/f/<formId>/schema` | The form's public field definition, see [shadcn/ui](https://ikiform.com/docs/shadcn.md#schema-endpoint) |
| `GET` | `/f/<formId>/thanks` | The hosted thank-you page |
| `GET` | `/f/<formId>/challenge` | The Ikiform human check frame, used by the SDK |

Opening `/f/<formId>` itself in a browser tab is a `GET`, which answers `404 not_found`. That is expected: the endpoint only takes posts.

## Body formats

| Content-Type | Shape | Notes |
| --- | --- | --- |
| `application/json` and `+json` types | One JSON object | Values can be strings, numbers, booleans, arrays and objects, nested at most 3 levels counting the top object |
| `application/x-www-form-urlencoded` | Name and value pairs | Repeated names and `name[]` become arrays |
| `multipart/form-data` | Name and value pairs | Same as urlencoded; real files are refused |
| Anything else |  | `415 unsupported_media_type` |

Bodies must be UTF-8. A `charset` other than `utf-8` gets `415 unsupported_charset`, and bytes that aren't valid UTF-8 get the same code. A JSON array or a malformed body gets `400 invalid_body`.

## Headers

### Request headers

| Header | Required | Effect |
| --- | --- | --- |
| `Content-Type` | Yes | Picks the body parser, see above |
| `Accept` | No | `application/json` forces a JSON answer, see [JSON or a redirect](https://ikiform.com/docs/how-it-works.md#response-modes) |
| `Idempotency-Key` | No | Makes retries safe, up to 255 characters, see [Idempotency](#idempotency) |
| `Authorization` | No | `Bearer ik_sk_...` or `Bearer ik_pub_...`, see [From a server](https://ikiform.com/docs/guides/server.md) |
| `Origin`, `Referer` | Sent by browsers | Checked against the form's allowed domains |

### Response headers

| Header | When | Value |
| --- | --- | --- |
| `X-Request-Id` | Every response | `req_...`, repeated as `request_id` in error bodies |
| `Retry-After` | `429` | Seconds until the next post is allowed |
| `Location` | `303` browser success | Your redirect or the hosted thank-you page |
| `Access-Control-Allow-Origin` | When the request has an `Origin` | The request's own origin |
| `Access-Control-Expose-Headers` | With CORS | `X-Request-Id, Retry-After`, so browser code can read both |
| `Cache-Control` | Success | `no-store` |

## CORS

The submission endpoint accepts cross-origin posts from any site. Preflights always succeed and echo the request's origin. No cookies or credentials are used, so CORS is not what protects your form: **allowed domains** are. With allowed domains set, a post from another site is stored as spam or refused, depending on the form's setting. See [Allowed domains](https://ikiform.com/docs/spam.md#allowed-domains).

`Preflight`:

```http
OPTIONS /f/frm_xxxxxxxxxxxxxxxx HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type, Accept, Idempotency-Key, Authorization
Access-Control-Max-Age: 86400
Vary: Origin
```

> The [REST API](https://ikiform.com/docs/api.md) under `/api/v1` is different: it sends no CORS headers and answers browser preflights with `405`, so a secret key can never be used from a web page.

## Responses

Success is `201` with the new submission id. Errors use one envelope everywhere, with field errors keyed by field id when validation fails. Every code is listed on [Errors](https://ikiform.com/docs/errors.md).

**201** (`Created`)

```json
{ "ok": true, "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3" }
```

**422** (`Validation failed`)

```json
{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": { "email": ["Enter a valid email address"] }
  },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}
```

> A post that scores as spam still gets `201`. Spam is stored separately and never reaches your webhooks or inbox.

## Idempotency

Send an `Idempotency-Key` header, or an `_idempotency` field, to make retries safe. Keys are up to 255 characters and are scoped to the form for 24 hours. The header wins when both are sent.

| Retry with | Result |
| --- | --- |
| The same key and the same fields | The first response is replayed. No second submission is created. |
| The same key and different fields | `422 idempotency_mismatch` |
| The same key while the first request is still running | `409 idempotency_in_progress` |

Posts that fail before the submission is stored, such as validation errors, don't keep the key, so you can fix the data and retry with the same key. A safe retry loop:

`retry.js`:

```js
const key = crypto.randomUUID();

async function send(attempt = 1) {
  const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
    method: "POST",
    headers: { "Content-Type": "application/json", "Idempotency-Key": key },
    body: JSON.stringify({ email: "ada@example.com" }),
  }).catch(() => null);
  if (response && response.status < 500 && response.status !== 429) return response.json();
  if (attempt === 3) throw new Error("Ikiform is unreachable");
  const wait = Number(response?.headers.get("Retry-After")) || attempt * 2;
  await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  return send(attempt + 1);
}
```

---

Source: https://ikiform.com/docs/shadcn

# shadcn/ui component

> Install a form component that renders your Ikiform fields with your own shadcn/ui components.

If your project uses shadcn/ui, you can install a ready-made form instead of writing the markup. It is one option among several: the same form keeps working with [plain HTML](https://ikiform.com/docs/html.md) and [fetch](https://ikiform.com/docs/frameworks.md).

## Install

`Terminal`:

```bash
npx shadcn@latest add https://ikiform.com/r/form.json
```

This copies `components/ikiform/form.tsx` into your project and installs the shadcn/ui components it uses: `button`, `checkbox`, `input`, `label`, `radio-group` and `textarea`. The file is yours to edit. Selects use a native `<select>`, so it works with both the Radix and Base UI flavours of shadcn/ui.

## Usage

`app/contact/page.tsx`:

```tsx
import { IkiForm } from "@/components/ikiform/form";

export default function Contact() {
  return <IkiForm form="frm_xxxxxxxxxxxxxxxx" />;
}
```

On mount the component fetches the form's public schema and renders one control per field, using the labels, placeholders, help text and options you set in the dashboard. Define fields first on the [Fields](https://ikiform.com/docs/fields.md) tab of the form; a form without fields renders no inputs.

- It validates in the browser with the same rules and messages as the server.
- It posts JSON with the honeypot and a signed render timestamp, which helps spam scoring.
- Server field errors appear under their fields; other errors appear above the button.
- On success it replaces the form with the form's success message.

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `form` | `string` | Required. The form id. |
| `fields` | `IkiFormField[]` | Replaces the fetched fields. Uses the same shape as field definitions. |
| `onSuccess` | `({ id, values }) => void` | Called after a successful submit. |
| `submitLabel` | `string` | Button text. Defaults to the form's submit label. |
| `successMessage` | `ReactNode` | Shown after submit. Defaults to the form's success message. |
| `turnstileSiteKey` | `string` | Only for forms with your own Turnstile keys and no site key saved in Ikiform. |
| `className` | `string` | Class names for the form element. |
| `baseUrl` | `string` | Defaults to `https://ikiform.com`. |

`app/waitlist/page.tsx`:

```tsx
import { IkiForm } from "@/components/ikiform/form";

export default function Waitlist() {
  return (
    <IkiForm
      form="frm_xxxxxxxxxxxxxxxx"
      submitLabel="Join the waitlist"
      successMessage="You're on the list."
      onSuccess={({ id }) => console.log("Submitted", id)}
    />
  );
}
```

### Fields in code

Pass `fields` to render without the dashboard definition. The server still validates against the form's published fields, so keep the two in sync.

`Fields in code`:

```tsx
<IkiForm
  form="frm_xxxxxxxxxxxxxxxx"
  fields={[
    { id: "email", type: "email", label: "Work email", required: true },
    { id: "team_size", type: "number", label: "Team size", validation: { min: 1, integer: true } },
  ]}
/>
```

## Human check

With the spam check set to **Ikiform**, the component embeds a small ikiform.com frame that stays hidden until Turnstile needs a click, and asks for a fresh token after every attempt. If the frame can't load, it offers to open the check in a new window. With your own Turnstile keys, it renders the Turnstile widget with the form's site key.

## The schema endpoint

The component reads `GET https://ikiform.com/f/<formId>/schema`. You can call it yourself to build your own renderer, or use `getSchema` from the [SDK](https://ikiform.com/docs/sdk.md#getschema).

`GET /f/:formId/schema`:

```json
{
  "id": "frm_xxxxxxxxxxxxxxxx",
  "title": "Contact",
  "description": null,
  "fields": [{ "id": "email", "type": "email", "label": "Email", "required": true }],
  "settings": { "submit_label": "Send", "success_message": "Thanks!" },
  "honeypot_field": "_gotcha",
  "turnstile_required": false,
  "turnstile_site_key": null,
  "challenge": null,
  "ts": "1792300000000.signature"
}
```

- Open to any origin (`Access-Control-Allow-Origin: *`) and never cached.
- Paused, disabled and unknown forms all return the same `404`.
- Only the published fields and display settings leave the server. Allowed domains, the redirect URL, spam settings and rate limits stay private.
- `challenge` is `{ "provider": "ikiform", "url": ... }`, `{ "provider": "custom", "site_key": ... }` or `null`. `ts` is a fresh signed render timestamp to send back as `_ikiform_ts`.
- It allows 60 requests a minute per visitor and form, separate from the submit allowance.

> The component source is plain React and Tailwind. Read it, restyle it, or delete the parts you don't need.

---

Source: https://ikiform.com/docs/guides/nextjs

# Next.js

> Submit from a Next.js App Router client component, or through a server action with a secret key.

There are two good ways to submit from Next.js. Post from the browser in a client component, which keeps each visitor's own IP for rate limits and works with every spam check. Or post from a server action, which keeps the form working without JavaScript.

|   | Client component | Server action |
| --- | --- | --- |
| Works without JavaScript | No | Yes |
| Rate limits count | Each visitor | Your server's IP |
| Ikiform human check | Use `challenge` from the SDK | Skipped with a secret key |
| Allowed domains | Checked against the browser's origin | Skipped with a secret key |
| Needs a secret key | No | Yes |

## Install the SDK

`Terminal`:

```bash
npm install @ikiform/sdk
```

The SDK is optional. Everything below also works with `fetch`; see [JavaScript and fetch](https://ikiform.com/docs/frameworks.md).

## From a client component

`app/contact/contact-form.tsx`:

```tsx
"use client";

import { submit } from "@ikiform/sdk";
import { useState } from "react";

type Status = "idle" | "sending" | "sent" | "error";

export function ContactForm() {
  const [status, setStatus] = useState<Status>("idle");
  const [errors, setErrors] = useState<Record<string, string[]>>({});
  const [message, setMessage] = useState("");

  async function onSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();
    setStatus("sending");
    const result = await submit("frm_xxxxxxxxxxxxxxxx", new FormData(event.currentTarget));
    if (result.ok) return setStatus("sent");
    setErrors(result.error.fields ?? {});
    setMessage(result.error.message);
    setStatus("error");
  }

  if (status === "sent") return <p>Thanks, we got it.</p>;

  return (
    <form onSubmit={onSubmit} noValidate>
      <label htmlFor="email">Email</label>
      <input id="email" name="email" type="email" required aria-invalid={Boolean(errors.email)} />
      {errors.email ? <p>{errors.email[0]}</p> : null}
      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" />
      <input name="_gotcha" type="text" tabIndex={-1} autoComplete="off" hidden />
      {status === "error" && !Object.keys(errors).length ? <p role="alert">{message}</p> : null}
      <button disabled={status === "sending"}>{status === "sending" ? "Sending" : "Send"}</button>
    </form>
  );
}
```

- `submit` never throws. It resolves to `{ ok: true, id }` or `{ ok: false, error, status, requestId }`.
- `error.fields` maps field ids to messages when the form has [fields](https://ikiform.com/docs/fields.md) defined.
- Render the component from any server component page, for example `app/contact/page.tsx`.

### With the Ikiform human check

If the form's spam check is **Ikiform**, get a token right before each submit. `challenge` mounts a small ikiform.com frame that stays invisible unless Turnstile needs a click.

`contact-form.tsx`:

```tsx
const data = new FormData(event.currentTarget);
const turnstileToken = await challenge("frm_xxxxxxxxxxxxxxxx");
const result = await submit("frm_xxxxxxxxxxxxxxxx", data, { turnstileToken });
```

Import it with `import { challenge, submit } from "@ikiform/sdk";`. Tokens are single use, so call it once per submit.

## From a server action

Create a secret key in the dashboard under **API keys** with the `submissions:write` scope, and store it as an environment variable. Never expose it to the browser: don't prefix it with `NEXT_PUBLIC_`.

`.env.local`:

```bash
IKIFORM_SECRET_KEY=ik_sk_your_secret_key
```

`app/contact/actions.ts`:

```ts
"use server";

export interface ContactState {
  ok: boolean;
  message: string;
  fields?: Record<string, string[]>;
}

export async function sendContact(_previous: ContactState, formData: FormData): Promise<ContactState> {
  const body = new URLSearchParams();
  for (const [name, value] of formData) {
    if (typeof value === "string" && !name.startsWith("$ACTION")) body.append(name, value);
  }
  const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
    method: "POST",
    headers: {
      Accept: "application/json",
      Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}`,
    },
    body,
  });
  const result = await response.json();
  if (result.ok) return { ok: true, message: "Thanks, we got it." };
  return { ok: false, message: result.error.message, fields: result.error.fields };
}
```

`app/contact/contact-form.tsx`:

```tsx
"use client";

import { useActionState } from "react";
import { type ContactState, sendContact } from "./actions";

const initial: ContactState = { ok: false, message: "" };

export function ContactForm() {
  const [state, action, pending] = useActionState(sendContact, initial);

  if (state.ok) return <p>{state.message}</p>;

  return (
    <form action={action}>
      <label htmlFor="email">Email</label>
      <input id="email" name="email" type="email" required />
      {state.fields?.email ? <p>{state.fields.email[0]}</p> : null}
      <label htmlFor="message">Message</label>
      <textarea id="message" name="message" />
      {state.message && !state.fields ? <p role="alert">{state.message}</p> : null}
      <button disabled={pending}>{pending ? "Sending" : "Send"}</button>
    </form>
  );
}
```

> Posts sent from your server all come from your server's IP address, so Ikiform's per-visitor rate limits count every visitor together. The Standard preset allows 5 posts a minute per IP and form, which a busy site can hit. Post from the browser when you can, or choose the Relaxed or Custom [rate limit](https://ikiform.com/docs/rate-limits.md) for forms you proxy through a server.

The SDK's `submit` can be used in a server action too, but it doesn't send an `Authorization` header, so a form with allowed domains or the Ikiform human check would reject or flag the post. Use `fetch` with the secret key as shown.

## Receive webhooks in a route handler

To act on each submission in your Next.js app, add a route handler. See [Receiving webhooks](https://ikiform.com/docs/guides/webhook-handlers.md#nextjs).

---

Source: https://ikiform.com/docs/guides/react

# React

> A React form with pending, error and success states, field errors and an optional human check.

This works in any React app: Vite, Remix, React Router, Gatsby or a Next.js client component. It posts straight from the browser, so each visitor counts toward their own rate limit.

## Install the SDK

`Terminal`:

```bash
npm install @ikiform/sdk
```

## A complete form

`contact-form.jsx`:

```jsx
import { challenge, submit } from "@ikiform/sdk";
import { useState } from "react";

const FORM_ID = "frm_xxxxxxxxxxxxxxxx";

export function ContactForm({ humanCheck = false }) {
  const [status, setStatus] = useState("idle");
  const [errors, setErrors] = useState({});
  const [message, setMessage] = useState("");

  async function onSubmit(event) {
    event.preventDefault();
    const data = new FormData(event.currentTarget);
    setStatus("sending");
    setErrors({});
    try {
      const turnstileToken = humanCheck ? await challenge(FORM_ID) : undefined;
      const result = await submit(FORM_ID, data, { turnstileToken });
      if (result.ok) return setStatus("sent");
      setErrors(result.error.fields ?? {});
      setMessage(result.error.message);
    } catch {
      setMessage("The human check didn't finish. Try again.");
    }
    setStatus("error");
  }

  if (status === "sent") return <p>Thanks, we got it.</p>;

  return (
    <form onSubmit={onSubmit}>
      <label>
        Email
        <input name="email" type="email" required />
      </label>
      {errors.email ? <p>{errors.email[0]}</p> : null}
      <label>
        Message
        <textarea name="message" />
      </label>
      {errors.message ? <p>{errors.message[0]}</p> : null}
      <input name="_gotcha" type="text" tabIndex={-1} autoComplete="off" hidden />
      {status === "error" && message ? <p role="alert">{message}</p> : null}
      <button disabled={status === "sending"}>Send</button>
    </form>
  );
}
```

- Pass `humanCheck` when the form's spam check is set to **Ikiform**. With the check off, leave it out.
- `challenge` rejects with a `ChallengeError` if the check fails or is aborted, which the `catch` turns into a message.
- Without the SDK, replace `submit` with `fetch` as on [JavaScript and fetch](https://ikiform.com/docs/frameworks.md#fetch).

## As a form action

In React 19, the value `submit` returns also satisfies the form action type, so it can be passed straight to `action`. React's internal `$ACTION_` fields are dropped before sending.

`newsletter.jsx`:

```jsx
import { submit } from "@ikiform/sdk";

export function Newsletter() {
  return (
    <form action={(data) => submit("frm_xxxxxxxxxxxxxxxx", data)}>
      <input name="email" type="email" required />
      <button>Subscribe</button>
    </form>
  );
}
```

## Validate before sending

`validate` uses the same rules and messages as the server for all 12 field types, so you can show errors before the request. The server stays the source of truth.

`validate.js`:

```js
import { getSchema, validate } from "@ikiform/sdk";

const schema = await getSchema("frm_xxxxxxxxxxxxxxxx");

function check(form) {
  if (!schema.ok) return {};
  return validate(schema.schema.fields, new FormData(form));
}
```

---

Source: https://ikiform.com/docs/guides/vue

# Vue

> A Vue single-file component that submits to Ikiform, plus a Nuxt server route with a secret key.

Vue posts from the browser with the SDK or `fetch`. No plugin or build step is needed beyond your usual setup.

## Install the SDK

`Terminal`:

```bash
npm install @ikiform/sdk
```

## A single-file component

`ContactForm.vue`:

```vue
<script setup>
import { submit } from "@ikiform/sdk";
import { ref } from "vue";

const status = ref("idle");
const errors = ref({});
const message = ref("");

async function onSubmit(event) {
  status.value = "sending";
  const result = await submit("frm_xxxxxxxxxxxxxxxx", new FormData(event.target));
  if (result.ok) {
    status.value = "sent";
    return;
  }
  errors.value = result.error.fields ?? {};
  message.value = result.error.message;
  status.value = "error";
}
</script>

<template>
  <p v-if="status === 'sent'">Thanks, we got it.</p>
  <form v-else @submit.prevent="onSubmit">
    <label>
      Email
      <input name="email" type="email" required />
    </label>
    <p v-if="errors.email">{{ errors.email[0] }}</p>
    <label>
      Message
      <textarea name="message"></textarea>
    </label>
    <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
    <p v-if="status === 'error' && !errors.email" role="alert">{{ message }}</p>
    <button :disabled="status === 'sending'">Send</button>
  </form>
</template>
```

For forms with the **Ikiform** human check, call `challenge(formId)` before `submit` and pass the token as `{ turnstileToken }`, as in the [React guide](https://ikiform.com/docs/guides/react.md#component).

## Nuxt server route

To post from the server instead, add a server route that forwards the body with a secret key. The page then posts JSON to your own route.

`server/api/contact.post.ts`:

```ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  return $fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}` },
    body,
    ignoreResponseError: true,
  });
});
```

> Posts sent from your server all come from your server's IP address, so Ikiform's per-visitor rate limits count every visitor together. The Standard preset allows 5 posts a minute per IP and form, which a busy site can hit. Post from the browser when you can, or choose the Relaxed or Custom [rate limit](https://ikiform.com/docs/rate-limits.md) for forms you proxy through a server.

---

Source: https://ikiform.com/docs/guides/svelte

# Svelte and SvelteKit

> A Svelte 5 component that posts from the browser, and a SvelteKit form action that posts with a secret key.

## Svelte component

Install the SDK with `npm install @ikiform/sdk`, then post the form from the browser:

`ContactForm.svelte`:

```svelte
<script>
  import { submit } from "@ikiform/sdk";

  let status = $state("idle");
  let errors = $state({});
  let message = $state("");

  async function onsubmit(event) {
    event.preventDefault();
    status = "sending";
    const result = await submit("frm_xxxxxxxxxxxxxxxx", new FormData(event.currentTarget));
    if (result.ok) {
      status = "sent";
      return;
    }
    errors = result.error.fields ?? {};
    message = result.error.message;
    status = "error";
  }
</script>

{#if status === "sent"}
  <p>Thanks, we got it.</p>
{:else}
  <form {onsubmit}>
    <label>
      Email
      <input name="email" type="email" required />
    </label>
    {#if errors.email}<p>{errors.email[0]}</p>{/if}
    <label>
      Message
      <textarea name="message"></textarea>
    </label>
    <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
    {#if status === "error" && !errors.email}<p role="alert">{message}</p>{/if}
    <button disabled={status === "sending"}>Send</button>
  </form>
{/if}
```

## SvelteKit form action

A form action works without JavaScript and is enhanced when it loads. The action posts to Ikiform with a secret key stored as `IKIFORM_SECRET_KEY`.

`src/routes/contact/+page.server.js`:

```js
import { env } from "$env/dynamic/private";
import { fail } from "@sveltejs/kit";

export const actions = {
  default: async ({ request }) => {
    const data = await request.formData();
    const body = new URLSearchParams();
    for (const [name, value] of data) if (typeof value === "string") body.append(name, value);
    const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
      method: "POST",
      headers: { Accept: "application/json", Authorization: `Bearer ${env.IKIFORM_SECRET_KEY}` },
      body,
    });
    const result = await response.json();
    if (!result.ok) return fail(response.status, { message: result.error.message, fields: result.error.fields ?? {} });
    return { sent: true };
  },
};
```

`src/routes/contact/+page.svelte`:

```svelte
<script>
  import { enhance } from "$app/forms";

  let { form } = $props();
</script>

{#if form?.sent}
  <p>Thanks, we got it.</p>
{:else}
  <form method="POST" use:enhance>
    <label>
      Email
      <input name="email" type="email" required />
    </label>
    {#if form?.fields?.email}<p>{form.fields.email[0]}</p>{/if}
    <label>
      Message
      <textarea name="message"></textarea>
    </label>
    {#if form?.message && !form?.fields?.email}<p role="alert">{form.message}</p>{/if}
    <button>Send</button>
  </form>
{/if}
```

> Posts sent from your server all come from your server's IP address, so Ikiform's per-visitor rate limits count every visitor together. The Standard preset allows 5 posts a minute per IP and form, which a busy site can hit. Post from the browser when you can, or choose the Relaxed or Custom [rate limit](https://ikiform.com/docs/rate-limits.md) for forms you proxy through a server.

---

Source: https://ikiform.com/docs/guides/astro

# Astro

> A zero-JavaScript Astro form, and the same form enhanced with a small client script.

Astro renders plain HTML by default, which is all Ikiform needs. Start with the static form and add the script only if you want to stay on the page after submit.

## Static form

`src/components/Contact.astro`:

```astro
---
const endpoint = "https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx";
---

<form action={endpoint} method="post">
  <label>
    Email
    <input name="email" type="email" required />
  </label>
  <label>
    Message
    <textarea name="message"></textarea>
  </label>
  <input type="hidden" name="_redirect" value="https://example.com/thanks" />
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
  <button>Send</button>
</form>
```

`_redirect` only works when the form has allowed domains that include your site; otherwise the browser lands on the hosted thank-you page. See [HTML forms](https://ikiform.com/docs/html.md#redirect-rules).

## Enhanced with a script

Astro bundles `<script>` tags, so you can import the SDK directly. Without JavaScript the form still posts normally.

`src/components/Contact.astro`:

```astro
<form id="contact" action="https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx" method="post">
  <input name="email" type="email" required />
  <textarea name="message"></textarea>
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
  <button>Send</button>
  <p role="status" data-status></p>
</form>

<script>
  import { submit } from "@ikiform/sdk";

  const form = document.querySelector("#contact");
  const status = form.querySelector("[data-status]");

  form.addEventListener("submit", async (event) => {
    event.preventDefault();
    status.textContent = "Sending";
    const result = await submit("frm_xxxxxxxxxxxxxxxx", new FormData(form));
    status.textContent = result.ok ? "Thanks, we got it." : result.error.message;
    if (result.ok) form.reset();
  });
</script>
```

---

Source: https://ikiform.com/docs/guides/javascript

# Plain JavaScript

> Progressively enhance an HTML form with fetch: inline field errors, a status message and no page reload.

This page needs no build step and no package. The form works as a normal HTML post when JavaScript is off; with it on, the script posts with `fetch` and shows the result inline.

`contact.html`:

```html
<form id="contact" action="https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx" method="post" novalidate>
  <label for="email">Email</label>
  <input id="email" name="email" type="email" required aria-describedby="email-error" />
  <p id="email-error" data-error-for="email"></p>
  <label for="message">Message</label>
  <textarea id="message" name="message"></textarea>
  <p id="message-error" data-error-for="message"></p>
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
  <button>Send</button>
  <p role="status" data-status></p>
</form>

<script type="module">
  const form = document.querySelector("#contact");
  const button = form.querySelector("button");
  const status = form.querySelector("[data-status]");

  function showErrors(fields = {}) {
    for (const slot of form.querySelectorAll("[data-error-for]")) {
      const messages = fields[slot.dataset.errorFor];
      slot.textContent = messages ? messages[0] : "";
      form.elements[slot.dataset.errorFor]?.setAttribute("aria-invalid", messages ? "true" : "false");
    }
  }

  form.addEventListener("submit", async (event) => {
    event.preventDefault();
    button.disabled = true;
    status.textContent = "Sending";
    try {
      const response = await fetch(form.action, {
        method: "POST",
        headers: { Accept: "application/json" },
        body: new FormData(form),
      });
      const result = await response.json();
      showErrors(result.ok ? {} : result.error.fields);
      status.textContent = result.ok ? "Thanks, we got it." : result.error.message;
      if (result.ok) form.reset();
    } catch {
      status.textContent = "Couldn't reach the server. Check your connection and try again.";
    } finally {
      button.disabled = false;
    }
  });
</script>
```

- `Accept: application/json` makes Ikiform answer with JSON instead of a redirect.
- `result.error.fields` is keyed by field id; the script writes the first message under each field.
- `fetch` only rejects on network failures. HTTP errors still resolve, with the error envelope in the body.
- A `429` response carries `Retry-After`, which browser code can read because Ikiform exposes it through CORS.

## With the Ikiform human check

The interstitial check page only appears for normal browser navigations. A `fetch` post to a form with the **Ikiform** check gets `403 challenge_required` instead. Use `challenge` from the [SDK](https://ikiform.com/docs/sdk.md#challenge) through your bundler, or let the form post without JavaScript.

---

Source: https://ikiform.com/docs/guides/server

# From a server

> Create submissions from a backend, script or integration with a secret API key.

Backends, cron jobs and integrations can post to the same endpoint as browsers. Add a secret API key so Ikiform knows the post is yours.

## Create a secret key

1. In the dashboard, open **API keys** and create a **secret** key.
2. Give it the `submissions:write` scope. Add `submissions:read` and `forms:read` only if the same key also reads data from the [REST API](https://ikiform.com/docs/api.md).
3. Copy the key. It starts with `ik_sk_` and is shown once; Ikiform stores only its hash.

## Send a submission

**Node** (`submit.ts`)

```ts
const response = await fetch("https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}`,
    "Idempotency-Key": order.id,
  },
  body: JSON.stringify({ email: order.email, plan: order.plan }),
});

const result = await response.json();
if (!result.ok) throw new Error(`${result.error.code}: ${result.error.message} (${result.request_id})`);
```

**curl** (`Terminal`)

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1234" \
  -d '{"email":"ada@example.com","plan":"team"}'
```

**Python** (`submit.py`)

```python
import os

import requests

response = requests.post(
    "https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx",
    json={"email": "ada@example.com", "plan": "team"},
    headers={
        "Authorization": f"Bearer {os.environ['IKIFORM_SECRET_KEY']}",
        "Idempotency-Key": "order_1234",
    },
    timeout=10,
)
result = response.json()
if not result["ok"]:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
```

## What a secret key changes

| Check | Without a key | With a secret key |
| --- | --- | --- |
| Allowed domains | Checked against `Origin` or `Referer` | Skipped |
| Ikiform human check | Required when turned on | Skipped |
| Your own Turnstile keys | Token required | Token still required |
| Rate limits | Per visitor IP and form | Still apply, per your server's IP |
| Field validation and spam scoring | Run | Run |

A key from another workspace, a revoked key, or a secret key without `submissions:write` gets `403 forbidden`. A malformed `Authorization` header is also refused rather than ignored, so a typo never silently downgrades to an anonymous post.

> Posts sent from your server all come from your server's IP address, so Ikiform's per-visitor rate limits count every visitor together. The Standard preset allows 5 posts a minute per IP and form, which a busy site can hit. Post from the browser when you can, or choose the Relaxed or Custom [rate limit](https://ikiform.com/docs/rate-limits.md) for forms you proxy through a server.

## Publishable keys

Publishable keys (`ik_pub_`) are for browsers. They can only submit, and only from the domains you list on the key. A post with a publishable key from any other site gets `403 origin_not_allowed`. They don't skip the human check or the form's own allowed domains.

> Never put a secret key in browser code, a mobile app or a public repository. Revoke it in the dashboard if it leaks.

## Retries

Servers retry. Send an `Idempotency-Key` that is stable for the thing you are submitting, such as an order id, and a retry will replay the first response instead of creating a duplicate. See [Idempotency](https://ikiform.com/docs/frameworks.md#idempotency).

---

Source: https://ikiform.com/docs/guides/site-builders

# Site builders

> Use Ikiform from no-code site builders that let you paste custom HTML, such as an embed or code block.

Ikiform works anywhere you can put a real HTML `<form>` on the page, because a plain form post needs no script. Most site builders offer an embed, code or custom HTML block. Paste a form into it and point the `action` at your endpoint.

> This only works when the builder renders your HTML as-is. A builder's own form widget usually posts to the builder's servers instead; use it only if it lets you set a custom action URL with the POST method.

## The embed

`Custom HTML block`:

```html
<form action="https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx" method="post" target="_top">
  <label>
    Email
    <input name="email" type="email" required />
  </label>
  <label>
    Message
    <textarea name="message"></textarea>
  </label>
  <input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
  <button>Send</button>
</form>

<style>
  form { display: grid; gap: 12px; max-width: 420px; font: inherit; }
  label { display: grid; gap: 4px; }
  input, textarea { font: inherit; padding: 8px 10px; border: 1px solid #d4d4d4; border-radius: 6px; }
  button { font: inherit; padding: 8px 14px; border-radius: 6px; border: 0; background: #111; color: #fff; }
</style>
```

- Builders often place custom code inside an iframe. `target="_top"` makes the thank-you page open in the whole window instead of inside the small frame. If the builder's frame doesn't allow top navigation, the result shows inside the frame.
- Set **Redirect after submit** on the form to send people back to a thank-you page on your site.
- Styles inside the block may not inherit your site's styles; the `<style>` above gives the form a clean starting point.

## Allowed domains

If you set allowed domains, list every address the site is served from: your custom domain and the builder's preview or staging domain. Posts from a domain that isn't listed are stored as spam by default, and show the reason `origin_mismatch` in the dashboard.

Some builders render embeds in a frame whose `Origin` is `null`. Ikiform then falls back to the `Referer`. If the builder strips both, posts can't be matched to a domain; leave allowed domains empty for that form, or set the mismatch policy to spam rather than reject.

## Human check

The **Ikiform** human check works with no extra code: the browser navigates to a short check page on ikiform.com, which sends the post on. Avoid **Your own Turnstile keys** in builders, since that needs Cloudflare's script on the page.

---

Source: https://ikiform.com/docs/guides/webhook-handlers

# Receiving webhooks

> Verified webhook handlers for a Next.js route handler, Express, a Cloudflare Worker and Python.

Every handler does the same four things: read the raw body, verify the signature, ignore deliveries it has already handled, and answer `2xx` within 15 seconds. The payload and headers are described on [Webhooks](https://ikiform.com/docs/webhooks.md).

## Next.js route handler

`app/api/webhooks/ikiform/route.ts`:

```ts
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export async function POST(request: Request) {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET!,
    });
    if (event.type === "submission.created") {
      await saveLead(event.id, event.data.fields);
    }
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response(error.reason, { status: 400 });
    }
    throw error;
  }
}
```

`request.text()` gives the raw body. Don't call `request.json()` first; re-serialized JSON no longer matches the signature.

## Express

`server.js`:

```js
import express from "express";
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

const app = express();

app.post("/webhooks/ikiform", express.text({ type: "application/json" }), async (req, res) => {
  try {
    const event = await verifyWebhook({
      payload: req.body,
      headers: req.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET,
    });
    if (event.type === "submission.created") await saveLead(event.id, event.data.fields);
    res.status(204).end();
  } catch (error) {
    if (error instanceof WebhookVerificationError) return res.status(400).send(error.reason);
    res.status(500).end();
  }
});

app.listen(3000);
```

`express.text({ type: "application/json" })` keeps the body as the exact string Ikiform sent. A global `express.json()` would parse it first, so mount the webhook route before it or exclude this path.

## Cloudflare Worker

`src/index.ts`:

```ts
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  LEADS: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    try {
      const event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
      if (event.type === "submission.created") {
        ctx.waitUntil(env.LEADS.put(event.id, JSON.stringify(event.data)));
      }
      return new Response(null, { status: 204 });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
  },
};
```

The SDK uses Web Crypto only, so it runs in Workers, Deno and Bun with no polyfills.

## Python

`app.py`:

```python
import base64
import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
secret = base64.b64decode(os.environ["IKIFORM_WEBHOOK_SECRET"].removeprefix("whsec_"))


def verify(body: bytes, headers) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signatures or not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    content = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(secret, content, hashlib.sha256).digest()).decode()
    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return True
    return False


@app.post("/webhooks/ikiform")
def ikiform_webhook():
    body = request.get_data()
    if not verify(body, request.headers):
        abort(400)
    event = request.get_json()
    if event["type"] == "submission.created":
        save_lead(event["id"], event["data"]["fields"])
    return "", 204
```

## Handle duplicates

A delivery can arrive more than once, for example when your server handled it but the response timed out. The `webhook-id` header and the payload's `id` are the delivery id and stay the same across retries. Store it with a unique constraint and skip work you have already done:

`leads.ts`:

```ts
async function saveLead(deliveryId: string, fields: Record<string, unknown>) {
  const inserted = await db.query(
    "insert into leads (delivery_id, fields) values ($1, $2) on conflict (delivery_id) do nothing returning id",
    [deliveryId, JSON.stringify(fields)],
  );
  if (inserted.rowCount === 0) return;
  await notifySales(fields);
}
```

## Testing locally

- Ikiform only delivers to public `https:` URLs on port 443, so `localhost` won't work. Expose your local server with a tunnel that gives you a public HTTPS URL, and use that URL for a test endpoint.
- Use **Send test** on the endpoint page. It sends an `endpoint.test` event once, with no retries.
- Paste a real delivery into the [signature verifier](https://ikiform.com/docs/webhooks.md#verifier) to check your secret and headers in the browser.

---

Source: https://ikiform.com/docs/guides/export

# Exporting submissions

> Download submissions as CSV from the dashboard, or export every submission with the REST API.

## CSV from the dashboard

Open **Submissions**, or a form's own submissions tab, set the filters you want and choose **Export CSV**. The file follows the filters on screen.

| Filter | Values |
| --- | --- |
| Form | One form, or all forms |
| Status | Received, spam, or both |
| Date range | Last 24 hours, last 7 days, last 30 days, or all time |

- Columns are `id`, `created_at`, `form`, `status`, then one column per field. For a single form, its defined fields come first, followed by any other field names found in the exported rows.
- Arrays of plain values are joined with a comma and a space. Objects are written as JSON.
- Values that start with `=`, `+`, `-`, `@`, a tab or a carriage return get a leading `'`, so spreadsheet apps don't run them as formulas.
- The file is UTF-8 with a byte order mark, so Excel opens accents correctly.
- One export holds up to 100,000 rows and 500 field columns. Narrow the filters for larger workspaces, or use the API.

## Everything with the REST API

For a full backup, a scheduled sync or more than 100,000 rows, page through the [REST API](https://ikiform.com/docs/api.md#list-submissions) with a secret key that has `submissions:read`. Lists are newest first and stable while new submissions arrive.

**Node** (`export.ts`)

```ts
import { createWriteStream } from "node:fs";
import { createClient } from "@ikiform/sdk";

const ikiform = createClient({ apiKey: process.env.IKIFORM_SECRET_KEY! });
const out = createWriteStream("submissions.jsonl");

for await (const submission of ikiform.submissions.iterate({
  formId: "frm_xxxxxxxxxxxxxxxx",
  status: "received",
  limit: 100,
})) {
  out.write(`${JSON.stringify(submission)}\n`);
}

out.end();
```

**Python** (`export.py`)

```python
import csv
import os

import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['IKIFORM_SECRET_KEY']}"
params = {"form_id": "frm_xxxxxxxxxxxxxxxx", "status": "received", "limit": 100}

with open("submissions.csv", "w", newline="", encoding="utf-8") as file:
    writer = None
    while True:
        page = session.get("https://ikiform.com/api/v1/submissions", params=params, timeout=30).json()
        for submission in page["data"]:
            row = {"id": submission["id"], "created_at": submission["created_at"], **submission["fields"]}
            if writer is None:
                writer = csv.DictWriter(file, fieldnames=list(row), extrasaction="ignore")
                writer.writeheader()
            writer.writerow(row)
        if not page["has_more"]:
            break
        params["cursor"] = page["next_cursor"]
```

> Each key can make 100 requests a minute. With `limit: 100`, that is up to 10,000 submissions a minute. The SDK's iterator throws an `IkiformError` with `retryAfter` on `429`; wait that many seconds and continue from the last cursor.

---

Source: https://ikiform.com/docs/fields

# Fields and validation

> Define fields once and Ikiform validates every submission on the server, with clear messages and typed values.

Fields are optional. A form without fields accepts any data your form sends. Once you publish fields, Ikiform validates every submission against them on the server, rejects bad data with clear messages, and stores clean, typed values.

## Defining fields

Open a form in the dashboard and go to **Fields**. Add fields in the visual editor or edit the JSON definition directly. Each field's `id` is the input `name` your form must send.

`Form definition`:

```json
{
  "version": 1,
  "title": "Contact",
  "fields": [
    { "id": "name", "type": "text", "label": "Name", "required": true, "validation": { "max_length": 120 } },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    {
      "id": "topic",
      "type": "select",
      "label": "Topic",
      "options": [
        { "value": "sales", "label": "Sales" },
        { "value": "support", "label": "Support" }
      ]
    },
    { "id": "message", "type": "textarea", "label": "Message", "validation": { "min_length": 10 } }
  ],
  "settings": { "submit_label": "Send", "success_message": "Thanks, we'll reply within a day." }
}
```

### The definition

| Key | Required | Rules |
| --- | --- | --- |
| `version` | Yes | Always `1` |
| `title` | Yes | 1 to 200 characters |
| `description` | No | Up to 2,000 characters |
| `fields` | Yes | 1 to 100 fields with unique ids, at most 2,000 options in total |
| `settings.submit_label` | No | 1 to 100 characters, used by renderers such as the [shadcn/ui component](https://ikiform.com/docs/shadcn.md) |
| `settings.success_message` | No | 1 to 1,000 characters |
| `settings.redirect_url` | No | An `http:` or `https:` URL up to 2,048 characters |
| `$schema` | No | Any string up to 200 characters, ignored |

Unknown keys are refused, at the top level and on every field, so a typo like `requried` shows up as an error when you save.

### Keys on every field

| Key | Required | Rules |
| --- | --- | --- |
| `id` | Yes | Lowercase snake_case, starts with a letter, at most 64 characters, for example `team_size` |
| `type` | Yes | One of the 12 types below |
| `label` | Yes | 1 to 200 characters. Used in error pages and notification emails |
| `required` | No | `true` makes an empty value an error |
| `placeholder` | No | Up to 200 characters |
| `help_text` | No | Up to 1,000 characters |

## Playground

The interactive playground on this page lets you edit a form definition and a sample JSON payload. It runs Ikiform's real validator in the browser and shows the exact `201` or `422` response the server would return, the stored, coerced values, and generated HTML markup for the form.

## Field types

| Type | Stored as | Accepts |
| --- | --- | --- |
| `text` | string | Any single-line text |
| `textarea` | string | Multi-line text |
| `email` | string, domain lowercased | One email address |
| `number` | number | Numbers, or numeric strings from HTML forms |
| `select` | string | One listed option value |
| `radio` | string | One listed option value |
| `multi_select` | string[] | Listed option values, duplicates removed |
| `checkbox` | boolean | `on`, `true`, `1`, `yes`, or nothing |
| `date` | string, `YYYY-MM-DD` | A real calendar date |
| `url` | string, normalized | A web address, `https://` added when missing |
| `phone` | string | Digits, spaces, `+ ( ) . -` |
| `rating` | integer | A whole number from 1 to `max` |

### text

| validation | Values | Default |
| --- | --- | --- |
| `min_length` | 0 to 10,000 | None |
| `max_length` | 1 to 10,000, or at most 256 with a pattern | 1,000, or 256 with a pattern |
| `pattern` | A regular expression up to 200 characters, matched against the whole value | None |
| `pattern_message` | 1 to 200 characters | `Invalid format` |

Patterns run with the `u` flag and must match the whole value. When you save, Ikiform refuses patterns that could backtrack catastrophically: backreferences, repeated groups that contain repeats or alternatives (`(a+)+`, `(a|b)*`), and too many nested repeats.

### textarea

| Key | Values | Default |
| --- | --- | --- |
| `validation.min_length` | 0 to 16,000 | None |
| `validation.max_length` | 1 to 16,000 | 10,000 |
| `rows` | 1 to 50, a display hint for renderers | None |

### email

| validation | Values | Default |
| --- | --- | --- |
| `allowed_domains` | 1 to 100 domains such as `example.com`, matched exactly | Any domain |

Addresses longer than 254 characters are refused. The domain part is stored lowercased; the part before `@` is kept as sent.

### number

| validation | Values | Default |
| --- | --- | --- |
| `min` | Any number | None |
| `max` | Any number, at least `min` | None |
| `integer` | `true` to refuse decimals | `false` |

### select, radio and multi_select

| Key | Values | Default |
| --- | --- | --- |
| `options` | 1 to 500 `{ "value", "label" }` objects with unique values, each 1 to 200 characters | Required |
| `validation.min_items` | `multi_select` only, 0 to 500 | 0, or 1 when required |
| `validation.max_items` | `multi_select` only, 1 to 500 | The number of options |

Only listed values are accepted. `select` and `radio` take one value; send `multi_select` as repeated names, `name[]` or a JSON array.

### checkbox

No extra keys. A missing checkbox is `false`. `required: true` means it must be checked, which suits consent boxes. Values other than `on`, `true`, `1`, `yes`, `off`, `false`, `0`, `no` or empty are refused.

### date

| validation | Values | Default |
| --- | --- | --- |
| `min` | A `YYYY-MM-DD` date | None |
| `max` | A `YYYY-MM-DD` date, on or after `min` | None |

### url

| validation | Values | Default |
| --- | --- | --- |
| `https_only` | `true` to refuse `http:` | `false` |
| `max_length` | 1 to 4,096 | 2,048 |

Only `http:` and `https:` URLs with a dotted hostname and no username or password are accepted. The stored value is the normalized URL.

### phone

| validation | Values | Default |
| --- | --- | --- |
| `e164` | `true` to require international format, stored without separators | `false` |

Without `e164`, a phone number needs 6 to 15 digits and is stored as sent. With it, `+1 (415) 555-0123` is stored as `+14155550123`.

### rating

| validation | Values | Default |
| --- | --- | --- |
| `max` | 2 to 10 | 5 |

## Coercion

HTML forms send everything as text. Ikiform turns it into the type each field declares before storing. With `name` as text, `email`, `guests` as a number, `newsletter` as a checkbox, `site` as a URL and `phone` as a phone field:

`Posted, urlencoded`:

```text
name=++Ada+Lovelace++&email=Ada@Example.COM&guests=3&newsletter=on&site=example.com&phone=%2B1%20415%20555%200123
```

`Stored, with phone set to e164`:

```json
{
  "name": "Ada Lovelace",
  "email": "Ada@example.com",
  "guests": 3,
  "newsletter": true,
  "site": "https://example.com/",
  "phone": "+14155550123"
}
```

- Values are trimmed. An empty string counts as missing.
- A field that expects one value refuses an array with more than one item.
- Numbers accept plain decimal and exponent notation up to 64 characters, such as `3`, `-2.5` or `1e3`.

## Validation errors

A submission that fails validation is rejected with `422 validation_failed` and nothing is stored. `error.fields` maps each field id to its messages. Browser posts see the same messages on a hosted error page, labelled with your field labels.

`422 Unprocessable Content`:

```json
{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": {
      "email": ["Enter a valid email address"],
      "website": ["Unknown field \"website\""]
    }
  },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}
```

### Unknown fields

With fields defined, any field that is not in the definition is rejected as `Unknown field "name"`. Reserved fields that start with `_`, the honeypot and `cf-turnstile-response` don't count. Without a definition, any field names are accepted.

### Messages

| Problem | Message |
| --- | --- |
| Missing required value | `This field is required` |
| Required checkbox unchecked | `This box must be checked` |
| Too short or too long | `Must be at least 10 characters`, `Must be at most 120 characters` |
| Pattern mismatch | Your `pattern_message`, or `Invalid format` |
| Email | `Enter a valid email address`, `Email must be at one of: example.com` |
| Number | `Enter a number`, `Enter a whole number`, `Must be at least 1` |
| Options | `Choose one of the listed options`, `Choose at least 2 options`, `Choose at most 3 options` |
| Date | `Enter a valid date (YYYY-MM-DD)`, `Must be on or after 2026-01-01` |
| URL | `Enter a valid URL`, `Enter a valid https:// URL` |
| Phone | `Enter a valid phone number`, `Use international format, e.g. +14155550123` |
| Rating | `Choose a rating`, `Rating must be at most 5` |

## Validating in the browser

The SDK's `validate` mirrors the server rules and messages for all 12 field types, so you can show errors before posting. The server stays the source of truth. See [validate](https://ikiform.com/docs/sdk.md#validate).

---

Source: https://ikiform.com/docs/spam

# Spam protection

> Honeypot, signed timestamps, spam scoring, a human check, allowed domains and rate limits.

Every form gets layered protection with no setup: a honeypot, a signed render timestamp, spam scoring and rate limits. On top of that you can add a human check and restrict the form to your own domains.

| Layer | On by default | Outcome |
| --- | --- | --- |
| [Rate limits](https://ikiform.com/docs/rate-limits.md) | Yes, Standard preset | `429 rate_limited` |
| [Allowed domains](#allowed-domains) | No | Spam, or `403 origin_not_allowed` |
| [Human check](#human-check) | No | `403 challenge_required` or a check page |
| [Honeypot](#honeypot) | Yes | +5 to the score |
| [Spam scoring](#scoring) | Yes | Spam at 5 or more |

## How spam is handled

A post that is judged as spam is stored with the status `spam` and still gets a normal success response, so bots learn nothing. Spam sends no webhooks and no emails, doesn't count toward your monthly usage, and is deleted after 30 days. Review it in the dashboard or with the [REST API](https://ikiform.com/docs/api.md#spam); marking a submission as not spam sends its webhooks then.

## Honeypot

Add a hidden input that people never fill in. The default name is `_gotcha`; you can change it per form under **Honeypot field** in the form's settings. Hiding techniques are on [HTML forms](https://ikiform.com/docs/html.md#honeypot).

`Honeypot`:

```html
<input name="_gotcha" type="text" tabindex="-1" autocomplete="off" hidden />
```

## Spam scoring

Each post gets a score from these signals. At 5 or more it is stored as spam.

| Signal | Reason in the dashboard | Score |
| --- | --- | --- |
| The honeypot is filled in | `honeypot` | +5 |
| Sent less than 2 seconds after the form rendered | `timestamp_fast` | +3 |
| The signed render timestamp is forged or older than 24 hours | `timestamp_invalid` | +3 |
| A link in a name or subject field | `url_in_name` | +3 |
| The same fields were sent to this form in the last 24 hours | `duplicate` | +3 |
| Three or more links in total | `many_urls` | +2 |
| A known spam phrase (22 built in) | `keyword` | +2 |
| An email address on a disposable email domain | `disposable_email` | +2 |

- The render timestamp only exists when the form is rendered by the SDK or the [shadcn/ui component](https://ikiform.com/docs/shadcn.md), which send a signed `_ikiform_ts`. Plain HTML posts without it are not penalised.
- A name field is any field whose name contains `name`, `firstname`, `lastname`, `fullname`, `surname` or `subject`, but not words like `company`, `website` or `domain`.
- Two reasons force spam regardless of score: `origin_mismatch` from [allowed domains](#allowed-domains) and `captcha_unavailable` when Turnstile can't be reached.

## Human check

Each form has a **Spam check** setting with three options. It is off by default, so existing `fetch` and curl integrations keep working when you create a form.

| Option | What it does |
| --- | --- |
| Off | No challenge. Honeypot, timestamp and scoring still run. |
| Ikiform (recommended) | Cloudflare Turnstile run by Ikiform on ikiform.com. No Cloudflare account or keys needed. |
| Your own Turnstile keys | Your Turnstile widget and secret key. The token's hostname is checked against your allowed domains. |

### How the Ikiform check runs

How the token is obtained depends on how you submit:

- **HTML form post:** the post without a token gets a short "Checking you're human" page on ikiform.com. It runs Turnstile and posts the original fields again with the token, then the browser follows your redirect as usual.
- **JavaScript:** call `challenge(formId)` from the SDK. It mounts a small ikiform.com frame that stays invisible unless Turnstile needs a click, and resolves with a token. Pass it to `submit` as `turnstileToken`. A `fetch` post without a token gets `403 challenge_required`.
- **shadcn/ui component:** handled for you.
- **Server with a secret key:** the check is skipped, since a server can't solve it.

`form.js`:

```js
import { challenge, submit } from "@ikiform/sdk";

const form = document.querySelector("form");

form.addEventListener("submit", async (event) => {
  event.preventDefault();
  const turnstileToken = await challenge("frm_xxxxxxxxxxxxxxxx");
  const result = await submit("frm_xxxxxxxxxxxxxxxx", new FormData(form), { turnstileToken });
  if (result.ok) form.replaceWith("Thanks, we got it.");
});
```

Tokens are single use and live 300 seconds, so get one per submit. A JSON post without a token gets `403 challenge_required` with a `challenge_url`; a token that fails verification gets `403 captcha_failed`.

`403 Forbidden`:

```json
{
  "ok": false,
  "error": {
    "code": "challenge_required",
    "message": "Complete the human check, then send the form again.",
    "challenge_url": "https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx/challenge"
  },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}
```

> If Turnstile itself can't be reached, the post is accepted and stored as spam with the reason `captcha_unavailable`, so you can restore it rather than lose it.

### Your own Turnstile keys

Paste your site key and secret key into the form's settings. The secret is encrypted at rest. Render the widget in your form so it adds `cf-turnstile-response` to the post, or pass the token to `submit` as `turnstileToken`. Posts without a valid token get `403 captcha_failed`, including posts with a secret API key.

## Allowed domains

List the domains your form lives on under **Allowed domains**. A post must then come from one of them or a subdomain, judged by the `Origin` header, or the `Referer` when there is no origin. Leave the list empty to accept posts from any site.

| Allowed domains | Post from | Matches |
| --- | --- | --- |
| `example.com` | `https://example.com` | Yes |
| `example.com` | `https://www.example.com` | Yes, subdomain |
| `example.com` | `http://localhost:3000` | No, add `localhost` while developing |
| `example.com` | `https://example.co` | No |
| `app.example.com` | `https://example.com` | No, a parent domain doesn't match |

**When a post comes from another site** decides what happens to a mismatch: **Mark as spam** (the default) or **Reject** with `403 origin_not_allowed`. Posts with a secret API key skip this check. Allowed domains also decide which `_redirect` targets are followed and where the Ikiform check frame may be embedded.

## Rate limits

Each form has a **Rate limit** preset, counted exactly per visitor IP and form. Standard allows 5 posts a minute, Relaxed 20 a minute and Strict 2 every 10 minutes. The full rules are on [Rate limits](https://ikiform.com/docs/rate-limits.md).

---

Source: https://ikiform.com/docs/rate-limits

# Rate limits

> Per-form rate limit presets with the exact numbers, how they refill, and what a 429 looks like.

Rate limits stop one visitor, or one script, from flooding a form. Every form has a preset, and every limit is counted exactly, before the body is read. A rejected post doesn't use up any allowance.

## Presets

| Preset | Per visitor and form | Good for |
| --- | --- | --- |
| Standard (default) | 5 a minute, at most 3 in 10 seconds | Most forms |
| Relaxed | 20 a minute | Forms behind a login, internal tools, events on shared Wi-Fi |
| Strict | 2 every 10 minutes | Contact and sales forms, where a repeat is a double click or a bot |
| Custom | 1 to 1,000 every 10 seconds, minute, 10 minutes, hour or day | One entry per person, kiosks and other special cases |

## The presets compared

A visitor who presses Send once a second for two minutes gets this many posts through, simulated with the same algorithm Ikiform runs:

| Preset | Accepted of 120 | Accepted at second |
| --- | --- | --- |
| Standard | 14 | 0, 1, 2, 4, 7, 12, 24, 36, 48, 60, 72, 84, ... |
| Relaxed | 59 | 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, ... |
| Strict | 2 | 0, 1 |

## How limits refill

Limits are a smooth allowance, not a fixed clock window. A quiet visitor starts with the full allowance and can use it at once. After that, one more post is allowed every window divided by limit: every 12 seconds for Standard, every 3 seconds for Relaxed and every 5 minutes for Strict. After a full quiet window the allowance is full again.

Standard also has a burst rule of 3 posts per 10 seconds, so its first burst is 3, not 5. Relaxed, Strict and Custom have no separate burst rule.

## Limits that always apply

| Rule | Limit | Counted per |
| --- | --- | --- |
| Flood guard, before the form is looked up | 600 a minute | IP, across every form |
| Cross-form | 30 a minute, or the Custom per-minute rate when higher | IP, across every form |
| Form-wide | 300 a minute, or a Custom cap of 1 to 10,000 | Form, across every visitor |
| `GET /f/<formId>/schema` | 60 a minute | IP and form |
| The Ikiform check frame | 60 a minute | IP and form |
| REST API | 100 a minute | API key |

Custom rates faster than the flood guard are refused when you save; for example, a 10-second window allows at most 100. Loading a form's schema or the human check never spends the submit allowance.

## Custom

- **Submissions per visitor:** a whole number from 1 to 1,000, and a window of 10 seconds, a minute, 10 minutes, an hour or a day.
- **Form-wide cap per minute:** optional, from 1 to 10,000. It replaces the 300 a minute default for the whole form.
- An hour or a day window suits one-entry-per-person forms such as giveaways or RSVPs. Remember that many people can share one IP, for example at an office or event.

## When a limit is hit

The post is refused with `429 rate_limited` and a `Retry-After` header with the whole seconds until the next post is allowed. Browser form posts see a hosted "Slow down" page. `fetch` code can read `Retry-After`, because Ikiform exposes it through CORS.

`429 Too Many Requests`:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-Request-Id: req_01k7v2c9t3e8m5q4x6z0a1b2c3
Content-Type: application/json; charset=utf-8

{"ok":false,"error":{"code":"rate_limited","message":"Too many requests. Please slow down."},"request_id":"req_01k7v2c9t3e8m5q4x6z0a1b2c3"}
```

1. Wait for `Retry-After` seconds before sending again.
2. If honest visitors hit the limit, switch the form to Relaxed or Custom.
3. If your server posts for visitors, every post shares your server's IP. See [From a server](https://ikiform.com/docs/guides/server.md#what-changes).

> Rate limit settings are private. They are never exposed by the schema endpoint or the REST API.

---

Source: https://ikiform.com/docs/webhooks

# Webhooks

> Signed webhook payloads, verifying the HMAC-SHA256 signature, the retry schedule and delivery logs.

Webhooks push each accepted submission to your server as it arrives. Deliveries are signed with the [Standard Webhooks](https://www.standardwebhooks.com) scheme, retried for about three days, and logged attempt by attempt in the dashboard. Ready-made handlers are in [Receiving webhooks](https://ikiform.com/docs/guides/webhook-handlers.md).

## Add an endpoint

1. In the dashboard, open **Webhooks** and choose **Add endpoint**.
2. Enter an HTTPS URL and pick one form, or all forms in the workspace.
3. Copy the signing secret. It starts with `whsec_` and is shown in full only once.
4. Send a test event to check your handler.

### Endpoint URLs

- `https:` only, on the default port 443, with no username or password in the URL, up to 2,048 characters.
- A public hostname. IP addresses, `localhost`, and names ending in `.local`, `.internal`, `.intranet`, `.lan`, `.home.arpa` or `.onion` are refused, as are ikiform.com, workers.dev and pages.dev.
- The hostname must resolve only to public addresses. Private, loopback, link-local and carrier-grade NAT ranges are refused.
- The URL is checked when you save it and again before every delivery. An endpoint that starts resolving to a private address is disabled.
- A workspace can have up to 3 endpoints. Enterprise has no limit.

## Events

| Type | Sent when | Retried |
| --- | --- | --- |
| `submission.created` | A submission is accepted, or a spam submission is marked as not spam | Yes |
| `endpoint.test` | You choose **Send test** on the endpoint page | No, one attempt |

Spam never triggers a webhook. Neither do submissions held because the workspace is over its monthly limit.

## The request

Each delivery is a `POST` with a JSON body and three signature headers, sent from Ikiform's delivery service with the user agent `Ikiform-Webhooks/1.0`.

`Headers`:

```http
POST /webhooks/ikiform HTTP/1.1
content-type: application/json
user-agent: Ikiform-Webhooks/1.0
webhook-id: dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
```

| Header | Value |
| --- | --- |
| `webhook-id` | The delivery id. The same on every retry of the same delivery, so use it to ignore duplicates |
| `webhook-timestamp` | Unix seconds when this attempt was signed. New on every attempt |
| `webhook-signature` | `v1,` plus a base64 HMAC-SHA256. Several space-separated values while a secret rotates |

### Payloads

**submission.created** (`Body`)

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-17T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-17T12:00:00.000Z",
    "truncated": false
  }
}
```

**endpoint.test** (`Body`)

```json
{
  "id": "dlv_01k7v2f0a6c8e2g4j6m8p0r2t4",
  "type": "endpoint.test",
  "timestamp": "2026-10-17T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "endpoint_id": "whk_01k7v2e1b3d5f7h9k1m3n5q7s9",
    "message": "This is a test event from Ikiform."
  }
}
```

**Truncated** (`Over 256 KB`)

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-17T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": {},
    "meta": { "origin": "https://example.com", "country": "GB" },
    "created_at": "2026-10-17T12:00:00.000Z",
    "truncated": true
  }
}
```

| Field | Description |
| --- | --- |
| `id` | The delivery id, the same as `webhook-id` |
| `type` | `submission.created` or `endpoint.test` |
| `timestamp` | When the delivery was created, in ISO 8601 UTC. The same on every retry |
| `api_version` | The payload version the endpoint was created with, currently `2026-10-17` |
| `data.submission_id` | The submission's id. Fetch it with the [REST API](https://ikiform.com/docs/api.md#get-submission) |
| `data.form` | The form's `id` and `name` |
| `data.fields` | The stored values. With fields defined, these are the validated, coerced values |
| `data.meta` | The same keys as the REST API's `meta`. Every key is present and any value can be `null`. The visitor's IP and its hash are never sent |
| `data.meta.user_agent` | The browser's user agent, up to 512 characters |
| `data.meta.origin`, `referrer` | Where the post came from, when the browser sent them |
| `data.meta.country` | Two-letter country code, from Cloudflare |
| `data.meta.subject`, `reply_to` | From the `_subject` and `_replyto` fields |
| `data.created_at` | When the submission was stored |
| `data.truncated` | `true` when the body would be over 256 KB, in which case `fields` is empty |

Any `meta` value can be `null`. Treat field values as untrusted input, just like a form post to your own server.

## Verify the signature

The signature is an HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed with the base64-decoded part of the secret after `whsec_`, then base64-encoded and sent after `v1,` in `webhook-signature`.

- Use the raw request body exactly as received. Parsing and re-serializing JSON changes the bytes.
- The header can hold several space-separated signatures. Accept the request if any `v1` signature matches.
- Compare in constant time, and reject timestamps more than 5 minutes from now.

### With the SDK

`verifyWebhook` does all of the above with Web Crypto and returns the parsed event, or throws `WebhookVerificationError` with a `reason`. It accepts a `Headers` object or a plain record such as Node's `req.headers`.

`app/api/webhooks/ikiform/route.ts`:

```ts
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export async function POST(request: Request) {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET!,
    });
    if (event.type === "submission.created") {
      console.log(event.data.fields);
    }
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response(error.reason, { status: 400 });
    }
    throw error;
  }
}
```

### Without the SDK

Any Standard Webhooks library works too. By hand it takes a few lines:

**Node** (`verify.js`)

```js
import { createHmac, timingSafeEqual } from "node:crypto";

const secret = Buffer.from(process.env.IKIFORM_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");

export function verify(body, headers) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${id}.${timestamp}.${body}`).digest();
  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}
```

**Python** (`verify.py`)

```python
import base64
import hashlib
import hmac
import os
import time

secret = base64.b64decode(os.environ["IKIFORM_WEBHOOK_SECRET"].removeprefix("whsec_"))


def verify(body: bytes, headers) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signatures or not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    content = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(secret, content, hashlib.sha256).digest()).decode()
    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return True
    return False
```

### Signature verifier

The interactive verifier on this page checks a secret, the three webhook headers and a raw body with the SDK's `verifyWebhook`, entirely in the browser. It can also generate a correctly signed example delivery. Nothing you paste leaves the page.

## Responding

| Your response | What Ikiform does |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| `410 Gone` | Fails the delivery and disables the endpoint right away |
| `429` or `503` with `Retry-After` | Retries after that delay, but no later than the next step of the schedule |
| A redirect | Not followed. Counts as a failure |
| Any other status, a timeout or a network error | Retries on the schedule below |

Do slow work after responding, for example in a queue. The first 4 KB of your response body is saved in the delivery log.

## Retries

A failed attempt is retried on this schedule, each delay with up to 20% random jitter either way. After the 9th attempt, about 3 d 6 h after the first, the delivery is marked failed.

| Attempt | Delay after the previous attempt | Time since the first attempt |
| --- | --- | --- |
| 1 | Immediately | 0 |
| 2 | 5 s | 5 s |
| 3 | 5 min | 5 min |
| 4 | 30 min | 35 min |
| 5 | 2 h | 2 h 35 min |
| 6 | 5 h | 7 h 35 min |
| 7 | 10 h | 17 h 35 min |
| 8 | 1 d | 1 d 18 h |
| 9 | 1 d 12 h | 3 d 6 h |

### Disabled endpoints

If every delivery to an endpoint fails for 5 days, the endpoint is disabled and workspace owners get an email. A `410 Gone` response or a destination that becomes private disables it immediately. Turn it back on from the endpoint page once it is fixed.

## Delivery logs

Each endpoint page lists its deliveries with their status. Expand one to see every attempt: when it ran, whether it was automatic, manual or a test, the status code, the duration, and the first 4 KB of your response or the error. Retry any delivery from there. Attempts are kept for 30 days and deliveries for 90 days.

## Rotating secrets

**Roll signing secret** creates a new secret. For the next 24 hours every delivery is signed with both the old and the new secret, so `webhook-signature` holds two values and you can deploy the new secret without dropping events.

---

Source: https://ikiform.com/docs/api

# REST API

> Read forms and submissions, move submissions in and out of spam, and delete them with a secret key.

The REST API lets your server read forms and submissions, move submissions in and out of spam, and delete them. It is JSON over HTTPS at `https://ikiform.com/api/v1`. The OpenAPI 3.1 document is at [/api/v1/openapi.json](https://ikiform.com/api/v1/openapi.json).

> Creating submissions is not part of `/api/v1`. Post to the form endpoint with a secret key instead; see [From a server](https://ikiform.com/docs/guides/server.md).

## API keys

Create keys in the dashboard under **API keys**. A key belongs to one workspace and only sees that workspace. The full key is shown once; Ikiform stores only its hash.

| Kind | Prefix | Use |
| --- | --- | --- |
| Secret | `ik_sk_` | For servers. Calls the REST API with the scopes you choose, and can create submissions. |
| Publishable | `ik_pub_` | For browsers. Can only submit forms, and only from the domains you list on the key. |

### Scopes

| Scope | Grants |
| --- | --- |
| `forms:read` | `GET /forms`, `GET /forms/:formId` |
| `submissions:read` | `GET /submissions`, `GET /submissions/:id` |
| `submissions:write` | `DELETE /submissions/:id`, `POST /submissions/:id/spam` and `/not-spam`, and posting to `/f/:formId` |

## Authentication

Send the secret key as a Bearer token. The API is server to server only: it sends no CORS headers and answers browser preflights with `405`, so a secret key can never work from a web page.

`Terminal`:

```bash
curl https://ikiform.com/api/v1/forms \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"
```

- A missing, malformed, unknown, revoked or expired key gets `401 unauthorized` with `WWW-Authenticate: Bearer`.
- A publishable key gets `403 forbidden` (`Publishable keys can only submit forms.`). A key without the needed scope gets `403 forbidden` with the scope named in the message.
- Responses are sent with `Cache-Control: no-store`.

The SDK examples below share one client:

`ikiform.ts`:

```ts
import { createClient } from "@ikiform/sdk";

const ikiform = createClient({ apiKey: process.env.IKIFORM_SECRET_KEY! });
```

## Request composer

The interactive request composer on this page builds a REST API request from an endpoint, filters and ids, and shows it as curl, fetch and SDK code. It never sends anything: the REST API is server to server and refuses browser requests by design.

## Endpoints

| Method | Path | Scope | Returns |
| --- | --- | --- | --- |
| `GET` | [`/forms`](#list-forms) | `forms:read` | List forms |
| `GET` | [`/forms/:formId`](#get-form) | `forms:read` | Get a form |
| `GET` | [`/submissions`](#list-submissions) | `submissions:read` | List submissions |
| `GET` | [`/submissions/:id`](#get-submission) | `submissions:read` | Get a submission |
| `POST` | [`/submissions/:id/spam`](#mark-spam) | `submissions:write` | Mark as spam |
| `POST` | [`/submissions/:id/not-spam`](#mark-not-spam) | `submissions:write` | Mark as not spam |
| `DELETE` | [`/submissions/:id`](#delete-submission) | `submissions:write` | Delete a submission |
| `GET` | `/openapi.json` | None | The OpenAPI document |
| `GET` | `/health` | None | `{ "ok": true }` |

### List forms

`GET /forms` with the `forms:read` scope.

- Newest first. Takes `limit` (1 to 100, default 25) and `cursor`.

**curl** (`Terminal`)

```bash
curl "https://ikiform.com/api/v1/forms?limit=10" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"
```

**SDK** (`ikiform.ts`)

```ts
const page = await ikiform.forms.list({ limit: 10 });
```

**fetch** (`fetch.js`)

```js
const response = await fetch("https://ikiform.com/api/v1/forms?limit=10", {
  headers: { Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}` },
});
const body = await response.json();
```

**Response** (`200 OK`)

```json
{
  "object": "list",
  "data": [
    {
      "object": "form",
      "id": "frm_xxxxxxxxxxxxxxxx",
      "name": "Contact",
      "status": "active",
      "submission_count": 42,
      "created_at": "2026-10-01T09:30:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "c3ViXzAxazd2MmM5dDNlOG01cTR4NnowYTFiMmMz"
}
```

### Get a form

`GET /forms/:formId` with the `forms:read` scope.

- A form id from another workspace returns `404`, exactly like one that doesn't exist.

**curl** (`Terminal`)

```bash
curl https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"
```

**SDK** (`ikiform.ts`)

```ts
const form = await ikiform.forms.get("frm_xxxxxxxxxxxxxxxx");
```

**fetch** (`fetch.js`)

```js
const response = await fetch("https://ikiform.com/api/v1/forms/frm_xxxxxxxxxxxxxxxx", {
  headers: { Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}` },
});
const body = await response.json();
```

**Response** (`200 OK`)

```json
{
  "object": "form",
  "id": "frm_xxxxxxxxxxxxxxxx",
  "name": "Contact",
  "status": "active",
  "submission_count": 42,
  "created_at": "2026-10-01T09:30:00.000Z"
}
```

### List submissions

`GET /submissions` with the `submissions:read` scope.

| Parameter | Values | Default |
| --- | --- | --- |
| `form_id` | A form id | All forms in the workspace |
| `status` | `received` or `spam` | Both |
| `limit` | 1 to 100 | 25 |
| `cursor` | `next_cursor` from the previous page | The first page |

- Newest first. A `form_id` from another workspace returns an empty list rather than an error, so ids can't be probed.

**curl** (`Terminal`)

```bash
curl "https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50" \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"
```

**SDK** (`ikiform.ts`)

```ts
const page = await ikiform.submissions.list({
  formId: "frm_xxxxxxxxxxxxxxxx",
  status: "received",
  limit: 50,
});
```

**fetch** (`fetch.js`)

```js
const response = await fetch("https://ikiform.com/api/v1/submissions?form_id=frm_xxxxxxxxxxxxxxxx&status=received&limit=50", {
  headers: { Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}` },
});
const body = await response.json();
```

**Response** (`200 OK`)

```json
{
  "object": "list",
  "data": [
    {
      "object": "submission",
      "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
      "form_id": "frm_xxxxxxxxxxxxxxxx",
      "status": "received",
      "fields": { "name": "Ada", "email": "ada@example.com" },
      "meta": {
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
        "origin": "https://example.com",
        "referrer": "https://example.com/contact",
        "country": "GB",
        "subject": null,
        "reply_to": "ada@example.com"
      },
      "spam": { "score": 0, "reasons": [] },
      "created_at": "2026-10-17T12:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "c3ViXzAxazd2MmM5dDNlOG01cTR4NnowYTFiMmMz"
}
```

### Get a submission

`GET /submissions/:id` with the `submissions:read` scope.

- Ids from another workspace return `404`, exactly like ids that don't exist.

**curl** (`Terminal`)

```bash
curl https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"
```

**SDK** (`ikiform.ts`)

```ts
const submission = await ikiform.submissions.get("sub_01k7v2c9t3e8m5q4x6z0a1b2c3");
```

**fetch** (`fetch.js`)

```js
const response = await fetch("https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3", {
  headers: { Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}` },
});
const body = await response.json();
```

**Response** (`200 OK`)

```json
{
  "object": "submission",
  "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
  "form_id": "frm_xxxxxxxxxxxxxxxx",
  "status": "received",
  "fields": { "name": "Ada", "email": "ada@example.com" },
  "meta": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
    "origin": "https://example.com",
    "referrer": "https://example.com/contact",
    "country": "GB",
    "subject": null,
    "reply_to": "ada@example.com"
  },
  "spam": { "score": 0, "reasons": [] },
  "created_at": "2026-10-17T12:00:00.000Z"
}
```

### Mark as spam

`POST /submissions/:id/spam` with the `submissions:write` scope.

- Moves a received submission to spam, lowers the form's `submission_count` and cancels its pending webhook deliveries.
- Calling it on a submission that is already spam returns it unchanged.

**curl** (`Terminal`)

```bash
curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/spam \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"
```

**SDK** (`ikiform.ts`)

```ts
const submission = await ikiform.submissions.markSpam("sub_01k7v2c9t3e8m5q4x6z0a1b2c3");
```

**fetch** (`fetch.js`)

```js
const response = await fetch("https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/spam", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}` },
});
const body = await response.json();
```

**Response** (`200 OK`)

```json
{
  "object": "submission",
  "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
  "form_id": "frm_xxxxxxxxxxxxxxxx",
  "status": "spam",
  "fields": { "name": "Ada", "email": "ada@example.com" },
  "meta": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
    "origin": "https://example.com",
    "referrer": "https://example.com/contact",
    "country": "GB",
    "subject": null,
    "reply_to": "ada@example.com"
  },
  "spam": { "score": 0, "reasons": [] },
  "created_at": "2026-10-17T12:00:00.000Z"
}
```

### Mark as not spam

`POST /submissions/:id/not-spam` with the `submissions:write` scope.

- Moves it back to received, clears its spam score and reasons, and sends `submission.created` to every matching webhook endpoint.
- Calling it on a received submission returns it unchanged.

**curl** (`Terminal`)

```bash
curl -X POST https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/not-spam \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"
```

**SDK** (`ikiform.ts`)

```ts
const submission = await ikiform.submissions.markNotSpam("sub_01k7v2c9t3e8m5q4x6z0a1b2c3");
```

**fetch** (`fetch.js`)

```js
const response = await fetch("https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3/not-spam", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}` },
});
const body = await response.json();
```

**Response** (`200 OK`)

```json
{
  "object": "submission",
  "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
  "form_id": "frm_xxxxxxxxxxxxxxxx",
  "status": "received",
  "fields": { "name": "Ada", "email": "ada@example.com" },
  "meta": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
    "origin": "https://example.com",
    "referrer": "https://example.com/contact",
    "country": "GB",
    "subject": null,
    "reply_to": "ada@example.com"
  },
  "spam": { "score": 0, "reasons": [] },
  "created_at": "2026-10-17T12:00:00.000Z"
}
```

### Delete a submission

`DELETE /submissions/:id` with the `submissions:write` scope.

- Permanently removes the submission and its webhook deliveries. There is no undo. Deleting again returns `404`.

**curl** (`Terminal`)

```bash
curl -X DELETE https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3 \
  -H "Authorization: Bearer $IKIFORM_SECRET_KEY"
```

**SDK** (`ikiform.ts`)

```ts
const result = await ikiform.submissions.delete("sub_01k7v2c9t3e8m5q4x6z0a1b2c3");
```

**fetch** (`fetch.js`)

```js
const response = await fetch("https://ikiform.com/api/v1/submissions/sub_01k7v2c9t3e8m5q4x6z0a1b2c3", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}` },
});
const body = await response.json();
```

**Response** (`200 OK`)

```json
{ "object": "submission", "id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3", "deleted": true }
```

## Objects

Objects are snake_case JSON with an `object` field. Timestamps are ISO 8601 in UTC with milliseconds. Submission ids are ordered by time (`sub_` plus 26 characters); form ids are random (`frm_` plus 16 characters).

| Form field | Description |
| --- | --- |
| `status` | `active`, `paused` or `disabled` |
| `submission_count` | Received submissions, not spam |

| Submission field | Description |
| --- | --- |
| `status` | `received` or `spam` |
| `fields` | The stored values |
| `meta` | `user_agent`, `origin`, `referrer`, `country`, `subject`, `reply_to`. Every key is present and any value can be `null`. The IP hash is never returned |
| `spam.score`, `spam.reasons` | The spam score and reasons, such as `honeypot` or `origin_mismatch` |

## Pagination

Lists are newest first and use opaque cursors.

1. Request without a cursor.
2. If `has_more` is true, send `next_cursor` as `cursor` with the same filters.
3. Stop when `next_cursor` is `null`.

Pages are stable while new submissions arrive: new ones appear on the first page, never as duplicates further down. Don't build or parse cursors yourself; an invalid one returns `400 invalid_request`.

**SDK** (`export.ts`)

```ts
for await (const submission of ikiform.submissions.iterate({ formId: "frm_xxxxxxxxxxxxxxxx" })) {
  console.log(submission.id, submission.fields);
}
```

**fetch** (`export.js`)

```js
let cursor = null;

do {
  const url = new URL("https://ikiform.com/api/v1/submissions");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.IKIFORM_SECRET_KEY}` },
  });
  const page = await response.json();
  for (const submission of page.data) console.log(submission.id);
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);
```

## Errors

Errors use the same envelope as form submissions. Every response has an `X-Request-Id` header, which errors repeat as `request_id`.

`403 Forbidden`:

```json
{
  "ok": false,
  "error": { "code": "forbidden", "message": "This API key is missing the forms:read scope." },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}
```

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | `limit`, `status`, `form_id` or `cursor` is invalid; the message names it |
| 401 | `unauthorized` | Missing or invalid key |
| 403 | `forbidden` | Publishable key, or a missing scope |
| 404 | `not_found` | Unknown route or id, or an id in another workspace |
| 405 | `method_not_allowed` | A browser preflight |
| 429 | `rate_limited` | Over the per-key rate limit |
| 500 | `server_error` | Something failed on our side; quote `request_id` |

## Rate limit

Each key can make 100 requests per 60 seconds. Over the limit, the API returns `429 rate_limited` with a `Retry-After` header in seconds. The SDK exposes it as `error.retryAfter`.

---

Source: https://ikiform.com/docs/sdk

# SDK reference

> The @ikiform/sdk package: submit, challenge, getSchema, validate, createClient and verifyWebhook.

`@ikiform/sdk` is a small TypeScript package for submitting forms, reading data from the REST API and verifying webhooks. It has no dependencies and uses only `fetch`, `FormData` and Web Crypto, so it runs in browsers, Node 20+, Bun, Deno and Cloudflare Workers. It ships as ESM with type declarations.

`Terminal`:

```bash
npm install @ikiform/sdk
```

| Import | From | Runs in |
| --- | --- | --- |
| `submit` | `@ikiform/sdk` | Browser or server |
| `challenge`, `ChallengeError` | `@ikiform/sdk` | Browser |
| `getSchema`, `validate`, `validateField` | `@ikiform/sdk` | Browser or server |
| `createClient`, `IkiformError` | `@ikiform/sdk` | Server only |
| `verifyWebhook`, `WebhookVerificationError` | `@ikiform/sdk/webhooks` | Server |

## submit

`submit(formId, data, options?)` posts to `/f/:formId` and resolves to a result. It never throws: HTTP errors return the error envelope, network failures return the code `network_error` and aborts return `aborted`.

`SubmitResult`:

```ts
type SubmitResult =
  | { ok: true; id: string }
  | {
      ok: false;
      error: { code: string; message: string; fields?: Record<string, string[]> };
      status: number | null;
      requestId: string | null;
    };
```

| data | Sent as |
| --- | --- |
| `FormData` with only text | `application/x-www-form-urlencoded` |
| `FormData` with a `File` | `multipart/form-data`, which Ikiform refuses until uploads are built |
| `URLSearchParams` | `application/x-www-form-urlencoded` |
| A plain object | `application/json` |

- React's `$ACTION_` fields are dropped from `FormData`.
- The return value also satisfies React's form action type, so `action={(data) => submit(id, data)}` works.
- `submit` sends `Accept: application/json`. It doesn't send an `Authorization` header; use `fetch` to post with an API key.

| Option | Description |
| --- | --- |
| `baseUrl` | Defaults to `https://ikiform.com`. |
| `signal` | An `AbortSignal` to cancel the request. |
| `idempotencyKey` | Sent as the `Idempotency-Key` header. |
| `turnstileToken` | Sent as `cf-turnstile-response` in whichever body format is used. |
| `fetch` | A custom `fetch` implementation. |

`submit.ts`:

```ts
import { submit } from "@ikiform/sdk";

const result = await submit("frm_xxxxxxxxxxxxxxxx", { email: "ada@example.com" }, {
  idempotencyKey: crypto.randomUUID(),
  signal: AbortSignal.timeout(10_000),
});

if (!result.ok) console.error(result.error.code, result.error.fields);
```

## challenge

For forms whose spam check is **Ikiform**. `challenge(formId, options?)` mounts a 300 pixel wide ikiform.com frame that stays at zero height unless Turnstile needs a click, resolves with a token and removes the frame. Tokens are single use and live 300 seconds, so call it once per submit.

| Option | Description |
| --- | --- |
| `container` | Where to mount the frame. Defaults to `document.body`. |
| `mode` | `"frame"` (default) or `"popup"`, for browsers that block the frame. The popup must be opened from a click. |
| `timeoutMs` | Reject after this many milliseconds. No timeout by default. |
| `signal` | An `AbortSignal`. |
| `baseUrl` | Defaults to `https://ikiform.com`. |

It rejects with `ChallengeError`, whose `code` is `challenge_failed`, `challenge_timeout` or `aborted`.

`challenge.ts`:

```ts
import { challenge, ChallengeError, submit } from "@ikiform/sdk";

async function send(form) {
  try {
    const turnstileToken = await challenge("frm_xxxxxxxxxxxxxxxx", { timeoutMs: 60_000 });
    return submit("frm_xxxxxxxxxxxxxxxx", new FormData(form), { turnstileToken });
  } catch (error) {
    if (!(error instanceof ChallengeError) || error.code !== "challenge_failed") throw error;
    const turnstileToken = await challenge("frm_xxxxxxxxxxxxxxxx", { mode: "popup" });
    return submit("frm_xxxxxxxxxxxxxxxx", new FormData(form), { turnstileToken });
  }
}
```

## getSchema

`getSchema(formId, options?)` fetches the form's public schema: its published fields, display settings, honeypot name and challenge mode. Like `submit` it never throws, resolving to `{ ok: true, schema }` or an error result. Options are `baseUrl`, `signal` and `fetch`. The response is described on the [shadcn/ui page](https://ikiform.com/docs/shadcn.md#schema-endpoint).

## validate

`validate(fields, data)` checks `FormData` or a plain object against field definitions and returns `Record<string, string>`, one message per invalid field, or an empty object. It uses the same rules and messages as the server for all 12 field types. `validateField(field, value)` checks one value and returns a message or `undefined`.

`validate.ts`:

```ts
import { getSchema, submit, validate } from "@ikiform/sdk";

const result = await getSchema("frm_xxxxxxxxxxxxxxxx");

if (result.ok) {
  const errors = validate(result.schema.fields, new FormData(form));
  if (Object.keys(errors).length === 0) {
    await submit("frm_xxxxxxxxxxxxxxxx", new FormData(form));
  }
}
```

## createClient

`createClient({ apiKey, baseUrl?, fetch? })` returns a client for the [REST API](https://ikiform.com/docs/api.md). It throws a `TypeError` if the key isn't a secret key, so keep it on the server.

| Method | Request |
| --- | --- |
| `forms.list({ limit, cursor })` | `GET /forms` |
| `forms.get(formId)` | `GET /forms/:formId` |
| `forms.iterate({ limit })` | Every form, following cursors |
| `submissions.list({ formId, status, limit, cursor })` | `GET /submissions` |
| `submissions.get(id)` | `GET /submissions/:id` |
| `submissions.iterate({ formId, status, limit })` | Every submission, following cursors |
| `submissions.markSpam(id)` | `POST /submissions/:id/spam` |
| `submissions.markNotSpam(id)` | `POST /submissions/:id/not-spam` |
| `submissions.delete(id)` | `DELETE /submissions/:id` |

Failures throw `IkiformError` with `code`, `status`, `requestId`, `message`, plus `fields` when present and `retryAfter` in seconds on `429`. Network failures throw with `code: "network_error"` and `status: 0`.

`client.ts`:

```ts
import { createClient, IkiformError } from "@ikiform/sdk";

const ikiform = createClient({ apiKey: process.env.IKIFORM_SECRET_KEY! });

const forms = await ikiform.forms.list({ limit: 10 });
const form = await ikiform.forms.get("frm_xxxxxxxxxxxxxxxx");

for await (const submission of ikiform.submissions.iterate({ formId: form.id, status: "received" })) {
  console.log(submission.id, submission.fields);
}

try {
  await ikiform.submissions.delete("sub_01k7v2c9t3e8m5q4x6z0a1b2c3");
} catch (error) {
  if (error instanceof IkiformError && error.status === 429) {
    console.log(`Retry in ${error.retryAfter} seconds`);
  }
}
```

## verifyWebhook

`verifyWebhook({ payload, headers, secret, toleranceSeconds? })` verifies a webhook signature and returns the parsed event. Pass the raw body string. The default tolerance is 300 seconds in both directions.

`webhook.ts`:

```ts
import { verifyWebhook, type WebhookEvent } from "@ikiform/sdk/webhooks";

const event = await verifyWebhook<WebhookEvent>({
  payload: rawBody,
  headers: request.headers,
  secret: process.env.IKIFORM_WEBHOOK_SECRET!,
  toleranceSeconds: 300,
});
```

### Verification errors

| reason | Meaning |
| --- | --- |
| `invalid_secret` | The secret isn't `whsec_` plus base64 |
| `missing_headers` | `webhook-id`, `webhook-timestamp` or `webhook-signature` is missing |
| `invalid_timestamp` | `webhook-timestamp` isn't whole Unix seconds |
| `timestamp_too_old` | Signed more than `toleranceSeconds` ago, for example a replayed request |
| `timestamp_too_new` | Signed in the future; check your server clock |
| `no_matching_signature` | No `v1` signature matches: wrong secret, or the body was changed |
| `invalid_payload` | The signature matched but the body isn't JSON |

> The event types are exported as `WebhookEvent`, `SubmissionCreatedEvent` and `EndpointTestEvent`. See [Webhooks](https://ikiform.com/docs/webhooks.md#payloads) for the full payload.

---

Source: https://ikiform.com/docs/errors

# Errors

> Every error code Ikiform returns, with its HTTP status, cause and fix.

Form submissions and the REST API share one error envelope. JSON requests get it with the matching HTTP status; browser form posts get a hosted error page with the same message and status.

## The error envelope

`Error`:

```json
{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please slow down."
  },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}
```

- `error.code` is stable; branch on it. `error.message` is plain English for people and may change.
- `error.fields` is present on validation errors, keyed by field id, each with a list of messages. Errors about the whole body use the key `_form`.
- `error.challenge_url` is present on `challenge_required`.
- `request_id` matches the `X-Request-Id` header that every response carries.
- Rate-limited responses carry `Retry-After` in seconds. Both headers are readable from browser code.

## Codes

| Status | Code | Where |
| --- | --- | --- |
| 400 | [`invalid_body`](#invalid-body) | Submit |
| 400 | [`invalid_request`](#invalid-request) | API |
| 401 | [`unauthorized`](#unauthorized) | API |
| 402 | [`plan_required`](#plan-required) | Submit |
| 403 | [`forbidden`](#forbidden) | Both |
| 403 | [`origin_not_allowed`](#origin-not-allowed) | Submit |
| 403 | [`form_paused`](#form-paused) | Submit |
| 403 | [`captcha_failed`](#captcha-failed) | Submit |
| 403 | [`challenge_required`](#challenge-required) | Submit |
| 404 | [`not_found`](#not-found) | Both |
| 405 | [`method_not_allowed`](#method-not-allowed) | API |
| 409 | [`idempotency_in_progress`](#idempotency-in-progress) | Submit |
| 413 | [`payload_too_large`](#payload-too-large) | Submit |
| 415 | [`unsupported_media_type`](#unsupported-media-type) | Submit |
| 415 | [`unsupported_charset`](#unsupported-charset) | Submit |
| 422 | [`validation_failed`](#validation-failed) | Submit |
| 422 | [`files_not_supported`](#files-not-supported) | Submit |
| 422 | [`too_deep`](#too-deep) | Submit |
| 422 | [`idempotency_mismatch`](#idempotency-mismatch) | Submit |
| 429 | [`rate_limited`](#rate-limited) | Both |
| 429 | [`quota_exceeded`](#quota-exceeded) | Submit |
| 500 | [`server_error`](#server-error) | Both |

### 400 invalid_body

|   |   |
| --- | --- |
| Message | `The request body could not be read.` |
| Cause | Malformed JSON or multipart, a JSON array or string instead of an object, or an idempotency key over 255 characters. |
| Fix | Send one JSON object, or let the browser or `FormData` build the body. |

### 400 invalid_request

|   |   |
| --- | --- |
| Message | `The request is invalid.` |
| Cause | `limit`, `status`, `form_id` or `cursor` is invalid. The message names the parameter. |
| Fix | Use `limit` 1 to 100, `status` `received` or `spam`, a real `frm_` id, and cursors exactly as returned. |

### 401 unauthorized

|   |   |
| --- | --- |
| Message | `A valid API key is required.` |
| Cause | No `Authorization` header, not a Bearer token, or an unknown, revoked or expired key. |
| Fix | Send `Authorization: Bearer ik_sk_...` with a live secret key. |

### 402 plan_required

|   |   |
| --- | --- |
| Message | `This form isn't accepting submissions right now.` |
| Cause | The workspace has no active plan. This can only happen once billing is turned on. |
| Fix | Choose a plan in the dashboard under **Settings**. |

### 403 forbidden

|   |   |
| --- | --- |
| Message | `You do not have access to this resource.` |
| Cause | The API key is malformed, belongs to another workspace, is publishable on the REST API, or lacks the needed scope. |
| Fix | Use a secret key from this workspace with the scope named in the message. |

### 403 origin_not_allowed

|   |   |
| --- | --- |
| Message | `This form does not accept submissions from this site.` |
| Cause | The post came from a site outside the form's allowed domains and the form rejects mismatches, or a publishable key was used from a domain not listed on the key. |
| Fix | Add the site to **Allowed domains** or to the key's domains. For server posts, use a secret key. |

### 403 form_paused

|   |   |
| --- | --- |
| Message | `This form is not accepting submissions right now.` |
| Cause | The form is paused in the dashboard. |
| Fix | Resume the form. |

### 403 captcha_failed

|   |   |
| --- | --- |
| Message | `The captcha check failed. Please try again.` |
| Cause | The Turnstile token is missing, expired, already used, or didn't verify. |
| Fix | Get a fresh token for every submit. With your own keys, check that the site key matches the secret. |

### 403 challenge_required

|   |   |
| --- | --- |
| Message | `Complete the human check, then send the form again.` |
| Cause | The form uses the Ikiform human check and a JSON post arrived without a token. |
| Fix | Call `challenge(formId)` from the SDK and pass the token, or use `error.challenge_url`. Server posts can send a secret key instead. |

### 404 not_found

|   |   |
| --- | --- |
| Message | `Not found.` |
| Cause | The form doesn't exist, was deleted or disabled, or the id or route is wrong. Also returned for a `GET` to `/f/<formId>`. |
| Fix | Copy the endpoint from the form's overview, and post rather than opening it in a tab. |

### 405 method_not_allowed

|   |   |
| --- | --- |
| Message | `This method is not allowed here.` |
| Cause | A browser preflight on the REST API, which is server to server only. |
| Fix | Call `/api/v1` from your backend. |

### 409 idempotency_in_progress

|   |   |
| --- | --- |
| Message | `A request with this idempotency key is still being processed.` |
| Cause | A request with this idempotency key is still being processed. |
| Fix | Wait a moment and retry with the same key; you'll get the first response. |

### 413 payload_too_large

|   |   |
| --- | --- |
| Message | `The submission is too large.` |
| Cause | The body, a field name, a value or the number of fields is over its limit. The message says which. |
| Fix | See [Limits](https://ikiform.com/docs/limits.md#submissions). Split large text across fields or store files elsewhere and send a link. |

### 415 unsupported_media_type

|   |   |
| --- | --- |
| Message | `Send the form as urlencoded, multipart or JSON.` |
| Cause | The `Content-Type` isn't urlencoded, multipart or JSON, or is missing. |
| Fix | Set `Content-Type: application/json` when posting JSON. |

### 415 unsupported_charset

|   |   |
| --- | --- |
| Message | `Only UTF-8 is supported.` |
| Cause | The body isn't UTF-8, or declares another charset. |
| Fix | Encode as UTF-8. Add `accept-charset="utf-8"` to old HTML forms. |

### 422 validation_failed

|   |   |
| --- | --- |
| Message | `Some fields are invalid.` |
| Cause | Fields failed validation. `error.fields` maps field ids to messages. |
| Fix | Show the messages next to the fields. See [Fields](https://ikiform.com/docs/fields.md#errors). |

### 422 files_not_supported

|   |   |
| --- | --- |
| Message | `File uploads are not supported yet.` |
| Cause | The post contains a file. File uploads are not built yet. |
| Fix | Remove file inputs, or upload files elsewhere and submit the link. |

### 422 too_deep

|   |   |
| --- | --- |
| Message | `The JSON body is nested too deeply.` |
| Cause | The JSON body is nested more than 3 levels deep, counting the top-level object. |
| Fix | Flatten the data, for example `{ "address_city": "London" }`. |

### 422 idempotency_mismatch

|   |   |
| --- | --- |
| Message | `This idempotency key was already used with a different payload.` |
| Cause | This idempotency key was already used for this form in the last 24 hours with different fields. |
| Fix | Use a new key for new data. Keep the same key only for exact retries. |

### 429 rate_limited

|   |   |
| --- | --- |
| Message | `Too many requests. Please slow down.` |
| Cause | Over a rate limit. `Retry-After` says how many seconds to wait. |
| Fix | Wait and retry. If real visitors hit it, change the form's [rate limit](https://ikiform.com/docs/rate-limits.md). |

### 429 quota_exceeded

|   |   |
| --- | --- |
| Message | `This form isn't accepting submissions right now.` |
| Cause | The workspace received 2 times its monthly submission limit this month. |
| Fix | Upgrade, or wait for the next month. See [Monthly usage](https://ikiform.com/docs/limits.md#monthly-usage). |

### 500 server_error

|   |   |
| --- | --- |
| Message | `Something went wrong on our side.` |
| Cause | Something failed on Ikiform's side. |
| Fix | Retry with backoff and an idempotency key. If it keeps happening, quote `request_id`. |

## Not errors

- Spam gets the same `201` or redirect as a real submission. Look for it under the spam filter in the dashboard.
- A `_redirect` that isn't allowed is ignored, and the browser lands on the hosted thank-you page.
- A `_replyto` that isn't one valid email address is ignored.

## Retrying

- Retry `429` after `Retry-After`, and `500`, `409` or network errors with backoff. Send an [idempotency key](https://ikiform.com/docs/frameworks.md#idempotency) so a retry never creates a duplicate.
- Don't retry other `4xx` errors unchanged. Fix the request first.

---

Source: https://ikiform.com/docs/limits

# Limits

> Body size, field counts, rate limits, monthly usage, webhooks and retention.

Fixed limits that apply to every workspace and form. Only monthly usage and the number of webhook endpoints depend on your plan.

## Submissions

| Limit | Value | Over the limit |
| --- | --- | --- |
| Request body | 256 KB | `413 payload_too_large` |
| Stored fields, serialized as JSON | 64 KB | `413 payload_too_large` |
| Fields per submission | 100 | `413 payload_too_large` |
| Field name length | 128 characters | `413 payload_too_large` |
| Field value size | 16 KB | `413 payload_too_large` |
| JSON depth | 3 levels, counting the top-level object | `422 too_deep` |
| `_subject` | 200 characters | Cut to length |
| Idempotency key | 255 characters, kept 24 hours | `400 invalid_body` |
| Files | Not built yet | `422 files_not_supported` |

## Form definitions

| Limit | Value |
| --- | --- |
| Fields per form | 100 |
| Options per field | 500 |
| Options per form | 2,000 |
| Field id | 64 characters, lowercase snake_case |
| Label | 200 characters |
| Help text | 1,000 characters |
| Text field | Up to 10,000 characters, 1,000 by default |
| Long text field | Up to 16,000 characters, 10,000 by default |
| Pattern | 200 characters |
| Allowed domains per form | 20 |

## Rate limits

| Applies to | Limit |
| --- | --- |
| Posts to one form from one IP, Standard | 5 a minute and 3 in 10 seconds |
| Posts to one form from one IP, other presets | Relaxed 20 a minute, Strict 2 every 10 minutes, or Custom |
| Posts to any form from one IP | 30 a minute, and never more than 600 a minute |
| Posts to one form in total | 300 a minute, or a Custom cap of 1 to 10,000 |
| `GET /f/<formId>/schema` | 60 a minute per IP and form |
| The Ikiform check frame | 60 a minute per IP and form |
| REST API | 100 requests per 60 seconds per key |

Details and the refill behaviour are on [Rate limits](https://ikiform.com/docs/rate-limits.md).

## Monthly usage

Each workspace has a monthly submission limit set by its plan; see [Pricing](https://ikiform.com/pricing). Months are calendar months in UTC. Only received submissions count; spam and rejected posts don't.

- The workspace's notification recipients get an email at 80% and at 100% of the limit.
- At 2 times the limit, new submissions are rejected with `429 quota_exceeded` until the next month or an upgrade, and workspace owners get an email.

### Between 100% and the ceiling

|   | Today | Once billing is on |
| --- | --- | --- |
| New submissions | Received as usual | Held: visitors see a normal success page, but held submissions stay hidden |
| Webhooks and emails | Sent | Not sent until the workspace upgrades |
| Kept for | Until you delete them | 30 days |

> Billing is not switched on yet. Until it is, no workspace is refused for not having a plan.

## Webhooks

| Limit | Value |
| --- | --- |
| Endpoints per workspace | 3, no limit on Enterprise |
| Payload size | 256 KB, then `fields` is left out and `truncated` is `true` |
| Response timeout | 15 seconds |
| Attempts | 9 over about 3 d 6 h |
| Auto-disable | After 5 days of failed deliveries, or on `410 Gone` |
| Old secret after rotation | 24 hours |
| Response body saved in the log | 4 KB |

## Notification emails

| Limit | Value |
| --- | --- |
| Emails per form per hour | 50, then one digest for the rest of the hour |
| Emails per form per hour, workspaces younger than 7 days | 10 |
| Recipients per email | 10 |
| Fields shown per email | 20, values cut at 500 characters |

## Retention

| Data | Kept for |
| --- | --- |
| Received submissions | Until you delete them |
| Spam submissions | 30 days |
| Held submissions | 30 days |
| Webhook deliveries | 90 days |
| Webhook attempts | 30 days |
| Idempotency keys | 24 hours |

> Need higher limits? Email hello@ikiform.com about Enterprise.

---

Source: https://ikiform.com/docs/troubleshooting

# Troubleshooting

> Fixes for CORS errors, origin mismatches, challenge_required, 429s, unknown fields and quota errors.

Start with the response. Every answer from Ikiform has an `X-Request-Id` header and, for errors, a stable `error.code`. This curl shows both, from the same origin your site would send:

`Terminal`:

```bash
curl -i https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Origin: https://example.com" \
  -d '{"email":"ada@example.com"}'
```

Seeing `5xx` errors or timeouts from Ikiform itself? Check [status.ikiform.com](https://status.ikiform.com) for current incidents first.

## The browser says CORS blocked the request

The submission endpoint allows every origin, so a real CORS failure usually means the request never reached Ikiform, or went to the wrong URL.

- Check the URL is `https://ikiform.com/f/<formId>` with the full `frm_` id, for example `frm_xxxxxxxxxxxxxxxx`, and no trailing path.
- You are calling `/api/v1` from a browser. The REST API refuses browsers by design; call it from your server.
- An ad blocker, privacy extension or corporate proxy blocked the request. Try a private window without extensions.
- Your site's own `Content-Security-Policy` blocks it. Add `https://ikiform.com` to `connect-src`, and to `form-action` for plain HTML posts.

Check the preflight directly; it should answer `204` with your origin echoed back:

`Terminal`:

```bash
curl -i -X OPTIONS https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Origin: https://example.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type"
```

## Submissions land in spam with origin_mismatch

The form has allowed domains and the post came from somewhere else. The dashboard shows `origin_mismatch` among the spam reasons.

- Add every domain the form is served from, including `www`, staging and preview domains. Subdomains of a listed domain already match.
- Add `localhost` while developing locally.
- Posts from your own server carry no `Origin`. Send a secret key, which skips the check.
- With **Reject** chosen instead of **Mark as spam**, the same posts get `403 origin_not_allowed`.

## 403 challenge_required

The form's spam check is set to **Ikiform** and the post had no Turnstile token.

1. Browser code: call `challenge(formId)` from the SDK right before each submit, and pass the token to `submit` as `turnstileToken`.
2. Server code: send `Authorization: Bearer ik_sk_...` with a secret key; secret keys skip the check.
3. Plain HTML posts never see this code; they get the check page instead. If you see it from a form post, something is sending `Accept: application/json`.
4. Testing with curl? Turn the check off for a test form, or use a secret key.

`403 captcha_failed` means a token was sent but didn't verify. Tokens are single use and expire after 300 seconds, so get a new one for every attempt.

## 429 rate_limited

- Read `Retry-After` and wait that many seconds.
- Testing by hand? The Standard preset allows 5 posts a minute from one IP, and 3 in 10 seconds. Switch a test form to Relaxed.
- Posting from your server for every visitor? All posts share your server's IP. Post from the browser, or choose Relaxed or Custom.
- Many people behind one office or event network share an IP too. Relaxed allows 20 a minute.

## 422 with Unknown field

The form has fields defined and the post sent a name that isn't in the definition. `error.fields` names it, for example `{ "website": ["Unknown field \"website\""] }`.

- Add the field to the definition, or remove the input.
- Rename the input to start with `_` if it is only a marker for you; reserved names are dropped, not validated.
- Check that the honeypot name matches the form's **Honeypot field** setting.
- Field ids are lowercase snake_case: `firstName` in your markup is not the same as `first_name` in the definition.

## 429 quota_exceeded

The workspace received 2 times its monthly limit this month and stops accepting submissions until the next month starts or the workspace upgrades. See [Monthly usage](https://ikiform.com/docs/limits.md#monthly-usage).

## Submissions don't show up

- Look under the spam filter. Spam gets a normal success response, so the visitor can't tell.
- Check the form isn't paused, and that the id in your `action` matches the dashboard.
- A browser post that shows Ikiform's error page was rejected; the page lists the reason.

## Webhooks fail

- `no_matching_signature`: verify against the raw body, before any JSON parsing, and check you copied the right `whsec_` secret. Paste a delivery into the [verifier](https://ikiform.com/docs/webhooks.md#verifier).
- `timestamp_too_old`: your server clock is off, or you are replaying an old delivery.
- Timeouts: answer within 15 seconds and do slow work afterwards.
- Redirects aren't followed. Use the final URL, including the trailing slash your framework expects.
- The endpoint was disabled after 5 days of failures or a `410`. Fix it, then turn it back on from the endpoint page.

---

Source: https://ikiform.com/blog/form-submissions-to-n8n

# Send form submissions to n8n

> Trigger an n8n workflow from every Ikiform submission, verify the webhook signature in a Code node, and route the data anywhere n8n connects.

Published 2026-10-23 · Guide, n8n · https://ikiform.com/blog/form-submissions-to-n8n

n8n is a good first stop for Ikiform submissions. One workflow can verify the delivery, then send it to Slack, a spreadsheet, a CRM and an email list at once, with no server of your own. This guide works for n8n Cloud and for self-hosted n8n.

Diagram: How a submission gets from your form to n8n

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform validates it, filters spam, stores it and posts a signed webhook to the n8n Webhook node.
3. A Code node checks the signature before anything else runs.
4. Later nodes send the fields to Slack, a sheet, a CRM or email.

Your form posts to Ikiform. Ikiform signs each submission and posts it to the n8n Webhook node.

## What you'll build

- A Webhook trigger that receives Ikiform's signed `POST`.
- A Code node that checks the signature and stops anything that wasn't sent by Ikiform.
- A branch that ignores test events and passes real submissions on to the rest of the workflow.

Diagram: The n8n workflow, node by node

1. The Webhook node receives Ikiform's POST with the raw body.
2. The Code node checks the signature. A bad signature throws, n8n answers 500, and Ikiform retries later.
3. Respond to Webhook answers 200 as soon as the check passes.
4. The If node lets submission.created events through to your actions and stops test events.

Respond only after the check, so a failed check shows up in Ikiform's delivery log.

## Before you start

- An Ikiform form that already receives submissions. The [quickstart](https://ikiform.com/docs.md) takes a few minutes.
- An n8n Cloud account, or a self-hosted n8n that's reachable on a public `https://` URL on port 443.
- On self-hosted n8n, the Code node needs the built-in `crypto` module. Set `NODE_FUNCTION_ALLOW_BUILTIN=crypto` on the n8n process, or on the task runner if you use external runners. n8n Cloud allows `crypto` already.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

Ikiform can't reshape this body, and n8n doesn't need it to. Every value is available to later nodes as an expression.

## Set it up

### Step 1: Add a Webhook trigger

1. Create a workflow and add the **Webhook** node as its trigger.
2. Set **HTTP Method** to `POST` and **Path** to something readable, like `ikiform`.
3. Leave **Authentication** on **None**. Ikiform can't send n8n's auth headers; the signature check in the next step does that job.
4. Set **Respond** to **Using 'Respond to Webhook' Node**.
5. Under **Options**, add **Raw Body** and turn it on. The signature covers the exact bytes Ikiform sent.

The node shows two URLs. The **Test URL** works only while the editor is listening for a test event. The **Production URL** works once the workflow is published. Ikiform needs the production one in the end.

### Step 2: Verify the signature in a Code node

Add a **Code** node after the Webhook. Set **Mode** to **Run Once for All Items** and **Language** to **JavaScript**, then paste this. Replace the placeholder with your endpoint's signing secret after you create it in step 5.

`Code node`:

```js
const crypto = require("crypto");

const SECRET = "whsec_paste_your_signing_secret_here";

const item = $input.first();
const headers = item.json.headers;
const raw = item.binary?.data
  ? (await this.helpers.getBinaryDataBuffer(0, "data")).toString("utf8")
  : JSON.stringify(item.json.body);

const id = headers["webhook-id"];
const timestamp = headers["webhook-timestamp"];
const signatures = headers["webhook-signature"] ?? "";
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!id || !timestamp || !(age <= 300)) throw new Error("Missing or stale Ikiform webhook headers");

const key = Buffer.from(SECRET.replace(/^whsec_/, ""), "base64");
const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${raw}`).digest();
const valid = signatures.split(" ").some((entry) => {
  const [version, value] = entry.split(",");
  const received = Buffer.from(value ?? "", "base64");
  return version === "v1" && received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
if (!valid) throw new Error("Invalid Ikiform webhook signature");

return [{ json: JSON.parse(raw) }];
```

Diagram: How the Code node checks an Ikiform signature

1. Read webhook-id, webhook-timestamp and the raw body exactly as received.
2. Reject the request if the timestamp is more than 5 minutes from now.
3. Base64-decode the part of the secret after whsec_ and use it as the HMAC key.
4. Compute HMAC-SHA256 of id.timestamp.body and base64-encode it.
5. Compare it, in constant time, with each v1 value in webhook-signature. There are two while a secret rotates.
6. If one matches: continue, returns the parsed event.
7. If none match: throw, n8n answers 500.

With **Raw Body** on, n8n keeps the original bytes in the item's `data` binary field. If your n8n version doesn't add it, the code falls back to `JSON.stringify` of the parsed body. That gives the same bytes, because Ikiform's body is compact JSON written by `JSON.stringify`.

A bad signature throws, the workflow stops before it responds, and n8n answers `500`. Ikiform then retries on its schedule, so a wrong secret costs you nothing: fix it and the next retry goes through.

> Anyone who can edit this workflow can read the secret. On plans with n8n Variables you can keep it there instead and read it with `$vars`.

### Step 3: Answer Ikiform right away

Add a **Respond to Webhook** node after the Code node and set **Respond With** to **No Data**. It answers `200` as soon as the signature checks out. Ikiform needs a `2xx` within 15 seconds, so answer before the slow work, not after it.

### Step 4: Skip test events and use the data

Add an **If** node with the condition `{{ $json.type }}` is equal to `submission.created`. Connect your real actions to its **true** branch. These expressions pick out the useful parts:

`Expressions`:

```text
{{ $json.data.form.name }}
{{ $json.data.fields.email }}
{{ $json.data.fields.message }}
{{ $json.data.submission_id }}
```

Field names match the `name` attribute of each input on your form. A form with a `company` input gives you `{{ $json.data.fields.company }}`.

### Step 5: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste the **Production URL** from the Webhook node into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "n8n", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 6: Paste the secret and publish

Paste the `whsec_` secret into the Code node, save, and publish the workflow. Older n8n versions call this turning the workflow **Active**. The production URL only answers while the workflow is published.

### Map fields with real data first

To see real field names in the editor before you publish, point the Ikiform endpoint at the **Test URL**, choose **Listen for test event** in n8n, and send one submission from your form. Then **Edit** the endpoint in Ikiform and switch it to the **Production URL**. Editing keeps the same signing secret.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in n8n's **Executions** list.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event runs the Webhook, Code and Respond nodes, then stops at the If node. A real submission continues down the **true** branch.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Because the Respond to Webhook node runs only after the signature check, a failing check shows up in Ikiform's delivery log as a `500`, and n8n shows the error in **Executions**.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `404` in the delivery log | The workflow isn't published, or the endpoint still uses the Test URL. Publish the workflow and use the Production URL. |
| `500` and **Invalid Ikiform webhook signature** in Executions | The secret in the Code node doesn't belong to this endpoint, or it has a typo. Copy it again, or use **Roll secret** and paste the new one. |
| `Cannot find module 'crypto'` | Self-hosted n8n blocks built-in modules by default. Set `NODE_FUNCTION_ALLOW_BUILTIN=crypto` and restart n8n. |
| **Missing or stale Ikiform webhook headers** | The request didn't come from Ikiform, or the n8n server clock is more than 5 minutes off. Ikiform signs every retry again, so a real retry is never stale. |
| `400 timestamp_too_old` | The signature is more than 5 minutes old. Check the server clock, and don't replay old deliveries by hand; use **Retry now** on the delivery instead, which signs it again. |
| Delivery log shows `redirect_not_followed` | The URL answers with a `3xx`. Use the final URL, with the exact path and trailing slash, so it answers `2xx` directly. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Avoid duplicate rows

Ikiform retries when it doesn't get a `2xx` in time, with the same `id` each time. If a later node writes rows or sends emails, drop repeats with n8n's **Remove Duplicates** node keyed on `{{ $json.id }}`, set to remove items processed in previous executions.

## Next steps

| Want to | Read |
| --- | --- |
| Post each submission to a channel | [Send form submissions to Slack](https://ikiform.com/blog/form-submissions-to-slack.md) |
| Add rows to a spreadsheet | [Send form submissions to Google Sheets](https://ikiform.com/blog/form-submissions-to-google-sheets.md) |
| Understand every header and retry | [Webhooks](https://ikiform.com/docs/webhooks.md) |
| Check a signature by hand | [Signature verifier](https://ikiform.com/docs/webhooks.md#verifier) |

n8n's own reference for the nodes used here: [Webhook](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/), [Code](https://docs.n8n.io/code/code-node/), [Respond to Webhook](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.respondtowebhook/) and [built-in module settings](https://docs.n8n.io/hosting/configuration/environment-variables/nodes/).

---

Source: https://ikiform.com/blog/form-submissions-to-slack

# Send form submissions to Slack

> Post every Ikiform submission to a Slack channel with an incoming webhook and a small relay that verifies the signature and formats the message.

Published 2026-10-23 · Guide, Slack · https://ikiform.com/blog/form-submissions-to-slack

A channel that lights up with each new lead or support request is one of the most useful things to wire to a form. This guide posts each Ikiform submission to Slack as a tidy message with one line per field.

Diagram: How a submission gets from your form to Slack

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and sends a signed webhook to your relay.
3. The relay checks the signature, turns the submission into Block Kit and posts it to the Slack webhook URL.
4. Slack answers the relay, and the relay answers Ikiform.

Ikiform signs the delivery. The relay checks it, turns it into Block Kit, and posts it to Slack.

## Why there's a relay

Slack's incoming webhooks accept a message shaped as `{ "text": ... }` or `{ "blocks": [...] }`. Ikiform sends a submission event shaped as `{ "type": ..., "data": ... }`, and Slack answers that with `400 no_text`.

> Ikiform sends its own JSON shape to every endpoint and can't send a custom or templated body. Slack expects its own shape, so pasting the Slack URL straight into Ikiform doesn't work. A small relay in between verifies the signature and reformats the message.

The relay is about 60 lines. It also keeps the Slack URL private, and it checks Ikiform's signature, so nobody else can post to your channel through it. If you'd rather not deploy code, use [n8n](https://ikiform.com/blog/form-submissions-to-n8n.md), [Zapier](https://ikiform.com/blog/form-submissions-to-zapier.md) or [Make](https://ikiform.com/blog/form-submissions-to-make.md) with their Slack actions.

> Slack's Workflow Builder can also start from a webhook, but only on paid plans, and its variables read only top-level JSON keys. Ikiform's fields sit under `data.fields`, so they can't be mapped there.

## Before you start

- An Ikiform form that already receives submissions.
- Permission to add apps to your Slack workspace.
- Somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app on Vercel or any other host.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Set it up

### Step 1: Create a Slack incoming webhook

1. Go to [api.slack.com/apps](https://api.slack.com/apps), choose **Create New App**, then **From scratch**. Name it, for example `Ikiform`, and pick your workspace.
2. Open **Incoming Webhooks** in the app's settings and turn on **Activate Incoming Webhooks**.
3. Choose **Add New Webhook to Workspace**, pick the channel, and confirm.
4. Copy the webhook URL. It looks like `https://hooks.slack.com/services/T000/B000/XXXX`.

Check it works before going further:

`Terminal`:

```bash
curl -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello from the terminal"}'
```

Slack answers `ok` and the message shows up in the channel. Treat the URL as a secret: anyone who has it can post to that channel, and Slack revokes URLs it finds in public code.

### Step 2: Write the relay

Pick the platform you already use. Both versions verify the signature with `@ikiform/sdk`, format the message, and turn Slack errors into answers Ikiform retries.

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  SLACK_WEBHOOK_URL: string;
}

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function escape(text: string) {
  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function toSlack(event: WebhookEvent) {
  if (event.type === "endpoint.test") return { text: "Ikiform test event received. Submissions will appear here." };
  const { form, fields, submission_id, truncated } = event.data;
  const lines = Object.entries(fields)
    .slice(0, 40)
    .map(([name, value]) => clip(`*${escape(name)}*\n${escape(valueText(value))}`, 2000));
  const sections = Array.from({ length: Math.ceil(lines.length / 10) }, (_, index) => ({
    type: "section",
    fields: lines.slice(index * 10, index * 10 + 10).map((text) => ({ type: "mrkdwn", text })),
  }));
  const note = truncated ? "Too large to show here. Open it in Ikiform." : `\`${submission_id}\``;
  return {
    text: `New submission on ${escape(form.name)}`,
    blocks: [
      { type: "header", text: { type: "plain_text", text: clip(`New submission: ${form.name}`, 150) } },
      ...sections,
      { type: "context", elements: [{ type: "mrkdwn", text: note }] },
    ],
  };
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await fetch(env.SLACK_WEBHOOK_URL, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(toSlack(event)),
    });
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Slack rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Slack answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/slack/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function escape(text: string) {
  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function toSlack(event: WebhookEvent) {
  if (event.type === "endpoint.test") return { text: "Ikiform test event received. Submissions will appear here." };
  const { form, fields, submission_id, truncated } = event.data;
  const lines = Object.entries(fields)
    .slice(0, 40)
    .map(([name, value]) => clip(`*${escape(name)}*\n${escape(valueText(value))}`, 2000));
  const sections = Array.from({ length: Math.ceil(lines.length / 10) }, (_, index) => ({
    type: "section",
    fields: lines.slice(index * 10, index * 10 + 10).map((text) => ({ type: "mrkdwn", text })),
  }));
  const note = truncated ? "Too large to show here. Open it in Ikiform." : `\`${submission_id}\``;
  return {
    text: `New submission on ${escape(form.name)}`,
    blocks: [
      { type: "header", text: { type: "plain_text", text: clip(`New submission: ${form.name}`, 150) } },
      ...sections,
      { type: "context", elements: [{ type: "mrkdwn", text: note }] },
    ],
  };
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await fetch(process.env.SLACK_WEBHOOK_URL!, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(toSlack(event)),
  });
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Slack rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Slack answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

Diagram: How the relay maps an Ikiform submission to Slack message

1. form.name: Contact becomes header: New submission: Contact.
2. fields.name: Ada becomes section field: name / Ada.
3. fields.email: ada@example.com becomes section field: email / ada@example.com.
4. fields.message: Hello becomes section field: message / Hello.
5. submission_id becomes context: sub_… id.

Up to 10 fields per section block. More fields start a new section.

For the sample submission above, the relay posts this to Slack:

`Slack message`:

```json
{
  "text": "New submission on Contact",
  "blocks": [
    { "type": "header", "text": { "type": "plain_text", "text": "New submission: Contact" } },
    {
      "type": "section",
      "fields": [
        { "type": "mrkdwn", "text": "*name*\nAda" },
        { "type": "mrkdwn", "text": "*email*\nada@example.com" },
        { "type": "mrkdwn", "text": "*message*\nHello" }
      ]
    },
    { "type": "context", "elements": [{ "type": "mrkdwn", "text": "`sub_01k7v2c9t3e8m5q4x6z0a1b2c3`" }] }
  ]
}
```

- Slack's limits are 10 fields per section and 2,000 characters per field, so long values are cut and the fields split across sections.
- `&`, `<` and `>` are escaped, so a visitor can't inject links or mentions.
- A `429` from Slack becomes a `503` with the same `Retry-After`, so Ikiform waits before it tries again. Any other Slack error becomes a `502`, which Ikiform retries.

### Step 3: Deploy it

### Cloudflare Worker

`Terminal`:

```bash
mkdir ikiform-slack && cd ikiform-slack
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

Save the Worker code as `src/index.ts`, then set the route in `wrangler.jsonc`:

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-slack",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

Add both secrets and deploy:

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put SLACK_WEBHOOK_URL
npx wrangler deploy
```

Your relay URL is `https://hooks.example.com/`.

### Next.js

Add `@ikiform/sdk` to the app, save the route handler, and set `IKIFORM_WEBHOOK_SECRET` and `SLACK_WEBHOOK_URL` in your host's environment variables. On Vercel the relay URL is `https://your-app.vercel.app/api/ikiform/slack`. Use the production domain: Vercel's deployment protection blocks requests to protected preview URLs.

### Step 4: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste your relay URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Slack #leads", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 5: Add the secret to the relay

Set `IKIFORM_WEBHOOK_SECRET` to the `whsec_` secret. On Cloudflare run `npx wrangler secret put IKIFORM_WEBHOOK_SECRET` again; it takes effect right away. On Vercel, update the variable and redeploy.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in Slack.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event posts a short line to the channel. A real submission posts the full message, with the submission id at the bottom.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What the relay tells Ikiform when Slack answers

1. Slack accepts the request: the relay answers 204, and Ikiform marks the delivery succeeded.
2. Slack is rate limited (429): the relay answers 503 with Slack's Retry-After, and Ikiform waits that long before it tries again.
3. Slack answers with any other error: the relay answers 502, and Ikiform retries, 8 retries over about 3 d 6 h.

Slack allows about one message per second per webhook. A burst of submissions can hit that, and the relay passes Slack's `Retry-After` back to Ikiform, so the extra messages arrive a little later rather than not at all.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| `502` with `Slack answered 400` | Slack refused the message. Check the relay's logs for Slack's error, such as `invalid_payload`, and that the Slack URL is copied in full. |
| `502` with `Slack answered 403` or `404` | The Slack webhook was revoked, the app was removed, or the channel was archived. Create a new webhook and update `SLACK_WEBHOOK_URL`. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| The same submission arrives twice | A retry after a slow or failed answer. Every retry carries the same `webhook-id`, so skip ids you've already handled. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

- Send each form to its own channel: add one Slack webhook per channel and one Ikiform endpoint per form. Pro allows 3 endpoints.
- Add a button that links to the submission in your own admin, using `data.submission_id`.
- Skip duplicates by storing the `webhook-id` header, as in [Receiving webhooks](https://ikiform.com/docs/guides/webhook-handlers.md#duplicates).

| Slack reference | Link |
| --- | --- |
| Incoming webhooks | [docs.slack.dev](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks) |
| Section block limits | [docs.slack.dev](https://docs.slack.dev/reference/block-kit/blocks/section-block) |
| Escaping text | [docs.slack.dev](https://docs.slack.dev/messaging/formatting-message-text) |
| Rate limits | [docs.slack.dev](https://docs.slack.dev/apis/web-api/rate-limits) |

---

Source: https://ikiform.com/blog/form-submissions-to-discord

# Send form submissions to Discord

> Post every Ikiform submission to a Discord channel as an embed, through a small relay that verifies the signature and formats the message.

Published 2026-10-23 · Guide, Discord · https://ikiform.com/blog/form-submissions-to-discord

Discord works well as a shared inbox for a small team or a community. This guide posts each Ikiform submission to a channel as an embed, with one field per form input and the submission id in the footer.

Diagram: How a submission gets from your form to Discord

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and sends a signed webhook to your relay.
3. The relay checks the signature, turns the submission into an embed and posts it to the Discord webhook URL.
4. Discord answers the relay, and the relay answers Ikiform.

Ikiform signs the delivery. The relay checks it, turns it into an embed, and posts it to Discord.

## Why there's a relay

A Discord webhook expects a message with at least one of `content`, `embeds`, `components`, `file` or `poll`. Ikiform sends a submission event shaped as `{ "type": ..., "data": ... }`, which has none of them, so Discord refuses it with `400`.

> Ikiform sends its own JSON shape to every endpoint and can't send a custom or templated body. Discord expects its own shape, so pasting the Discord URL straight into Ikiform doesn't work. A small relay in between verifies the signature and reformats the message.

The relay also keeps the Discord URL private and checks Ikiform's signature, so nobody else can post to your channel through it. If you'd rather not deploy code, use [n8n](https://ikiform.com/blog/form-submissions-to-n8n.md), [Zapier](https://ikiform.com/blog/form-submissions-to-zapier.md) or [Make](https://ikiform.com/blog/form-submissions-to-make.md) with their Discord actions.

## Before you start

- An Ikiform form that already receives submissions.
- The **Manage Webhooks** permission on the Discord server.
- Somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app on Vercel or any other host.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Set it up

### Step 1: Create a Discord webhook

1. Open **Server Settings**, then **Integrations**, then **Webhooks**.
2. Choose **New Webhook**. Give it a name, such as `Ikiform`, and pick the channel.
3. Choose **Copy Webhook URL**. It looks like `https://discord.com/api/webhooks/123/abc`.

Check it works before going further:

`Terminal`:

```bash
curl -X POST "$DISCORD_WEBHOOK_URL?wait=true" \
  -H "Content-Type: application/json" \
  -d '{"content":"Hello from the terminal"}'
```

With `?wait=true`, Discord answers `200` with the message it created. Without it, Discord answers `204` even when the message wasn't saved, so the relay always adds it. Treat the URL as a secret: anyone who has it can post to that channel.

### Step 2: Write the relay

Pick the platform you already use. Both versions verify the signature with `@ikiform/sdk`, build the embed, and turn Discord errors into answers Ikiform retries.

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  DISCORD_WEBHOOK_URL: string;
}

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function withWait(url: string) {
  const target = new URL(url);
  target.searchParams.set("wait", "true");
  return target.toString();
}

interface EmbedField {
  name: string;
  value: string;
  inline: boolean;
}

function toDiscord(event: WebhookEvent) {
  const allowed_mentions = { parse: [] };
  if (event.type === "endpoint.test") {
    return { content: "Ikiform test event received. Submissions will appear here.", allowed_mentions };
  }
  const { form, fields, submission_id, created_at, truncated } = event.data;
  const title = clip(`New submission: ${form.name}`, 256);
  const description = truncated ? "Too large to show here. Open it in Ikiform." : undefined;
  let budget = 6000 - title.length - submission_id.length - (description?.length ?? 0);
  const embedFields: EmbedField[] = [];
  for (const [name, value] of Object.entries(fields).slice(0, 25)) {
    const field = {
      name: clip(name.trim() || "(unnamed)", 256),
      value: clip(valueText(value).trim() || "(empty)", 1024),
      inline: false,
    };
    if (field.name.length + field.value.length > budget) break;
    budget -= field.name.length + field.value.length;
    embedFields.push(field);
  }
  return {
    allowed_mentions,
    embeds: [{ title, description, fields: embedFields, footer: { text: submission_id }, timestamp: created_at }],
  };
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await fetch(withWait(env.DISCORD_WEBHOOK_URL), {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(toDiscord(event)),
    });
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Discord rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Discord answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/discord/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function withWait(url: string) {
  const target = new URL(url);
  target.searchParams.set("wait", "true");
  return target.toString();
}

interface EmbedField {
  name: string;
  value: string;
  inline: boolean;
}

function toDiscord(event: WebhookEvent) {
  const allowed_mentions = { parse: [] };
  if (event.type === "endpoint.test") {
    return { content: "Ikiform test event received. Submissions will appear here.", allowed_mentions };
  }
  const { form, fields, submission_id, created_at, truncated } = event.data;
  const title = clip(`New submission: ${form.name}`, 256);
  const description = truncated ? "Too large to show here. Open it in Ikiform." : undefined;
  let budget = 6000 - title.length - submission_id.length - (description?.length ?? 0);
  const embedFields: EmbedField[] = [];
  for (const [name, value] of Object.entries(fields).slice(0, 25)) {
    const field = {
      name: clip(name.trim() || "(unnamed)", 256),
      value: clip(valueText(value).trim() || "(empty)", 1024),
      inline: false,
    };
    if (field.name.length + field.value.length > budget) break;
    budget -= field.name.length + field.value.length;
    embedFields.push(field);
  }
  return {
    allowed_mentions,
    embeds: [{ title, description, fields: embedFields, footer: { text: submission_id }, timestamp: created_at }],
  };
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await fetch(withWait(process.env.DISCORD_WEBHOOK_URL!), {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(toDiscord(event)),
  });
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Discord rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Discord answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

Diagram: How the relay maps an Ikiform submission to Discord embed

1. form.name: Contact becomes title: New submission: Contact.
2. fields.name: Ada becomes field: name / Ada.
3. fields.email: ada@example.com becomes field: email / ada@example.com.
4. fields.message: Hello becomes field: message / Hello.
5. submission_id becomes footer: sub_….
6. created_at becomes timestamp.

Up to 25 fields per embed. allowed_mentions is empty, so nobody gets pinged.

For the sample submission above, the relay posts this to Discord:

`Discord message`:

```json
{
  "allowed_mentions": { "parse": [] },
  "embeds": [
    {
      "title": "New submission: Contact",
      "fields": [
        { "name": "name", "value": "Ada", "inline": false },
        { "name": "email", "value": "ada@example.com", "inline": false },
        { "name": "message", "value": "Hello", "inline": false }
      ],
      "footer": { "text": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3" },
      "timestamp": "2026-10-23T12:00:00.000Z"
    }
  ]
}
```

- Discord allows 25 fields per embed, 256 characters per field name, 1,024 per value and 6,000 across the whole embed. The relay cuts long values and stops adding fields before the total runs out.
- Discord trims whitespace and refuses empty values, so an empty input shows as "(empty)".
- `allowed_mentions` with an empty `parse` list means a visitor who types `@everyone` or a user id can't ping anyone.
- A `429` from Discord becomes a `503` with the same `Retry-After`, so Ikiform waits before it tries again. Any other Discord error becomes a `502`, which Ikiform retries.

### Step 3: Deploy it

### Cloudflare Worker

`Terminal`:

```bash
mkdir ikiform-discord && cd ikiform-discord
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

Save the Worker code as `src/index.ts`, then set the route in `wrangler.jsonc`:

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-discord",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

Add both secrets and deploy:

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put DISCORD_WEBHOOK_URL
npx wrangler deploy
```

Your relay URL is `https://hooks.example.com/`.

### Next.js

Add `@ikiform/sdk` to the app, save the route handler, and set `IKIFORM_WEBHOOK_SECRET` and `DISCORD_WEBHOOK_URL` in your host's environment variables. On Vercel the relay URL is `https://your-app.vercel.app/api/ikiform/discord`. Use the production domain: Vercel's deployment protection blocks requests to protected preview URLs.

### Step 4: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste your relay URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Discord #submissions", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 5: Add the secret to the relay

Set `IKIFORM_WEBHOOK_SECRET` to the `whsec_` secret. On Cloudflare run `npx wrangler secret put IKIFORM_WEBHOOK_SECRET` again; it takes effect right away. On Vercel, update the variable and redeploy.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in Discord.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event posts a short line to the channel. A real submission posts the embed, with the submission id in the footer and the submission time next to it.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What the relay tells Ikiform when Discord answers

1. Discord accepts the request: the relay answers 204, and Ikiform marks the delivery succeeded.
2. Discord is rate limited (429): the relay answers 503 with Discord's Retry-After, and Ikiform waits that long before it tries again.
3. Discord answers with any other error: the relay answers 502, and Ikiform retries, 8 retries over about 3 d 6 h.

Each Discord webhook has its own rate limit. A burst of submissions can hit it, and the relay passes Discord's `Retry-After` back to Ikiform, so the extra messages arrive a little later rather than not at all.

> If a Discord webhook answers `404`, it was deleted. Discord asks clients to stop calling deleted webhooks, so create a new one and update `DISCORD_WEBHOOK_URL` rather than letting retries run.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| `502` with `Discord answered 400` | Discord refused the message. Check the relay's logs for Discord's error body. A forum channel needs `thread_name` or `thread_id`, so post to a text channel instead. |
| `502` with `Discord answered 401` or `404` | The webhook was deleted or its token is wrong. Create a new webhook and update `DISCORD_WEBHOOK_URL`. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| The same submission arrives twice | A retry after a slow or failed answer. Every retry carries the same `webhook-id`, so skip ids you've already handled. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

- Send each form to its own channel: add one Discord webhook per channel and one Ikiform endpoint per form. Pro allows 3 endpoints.
- Post into a thread by adding `thread_id` to the webhook URL. The relay keeps any query string you put there.
- Skip duplicates by storing the `webhook-id` header, as in [Receiving webhooks](https://ikiform.com/docs/guides/webhook-handlers.md#duplicates).

| Discord reference | Link |
| --- | --- |
| Execute webhook | [docs.discord.com](https://docs.discord.com/developers/resources/webhook) |
| Embed limits | [docs.discord.com](https://docs.discord.com/developers/resources/message) |
| Rate limits | [docs.discord.com](https://docs.discord.com/developers/topics/rate-limits) |
| Intro to webhooks | [support.discord.com](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) |

---

Source: https://ikiform.com/blog/form-submissions-to-zapier

# Send form submissions to Zapier

> Start a Zap from every Ikiform submission with Webhooks by Zapier, check the signature in a Code step, and send the fields to any of Zapier's apps.

Published 2026-10-23 · Guide, Zapier · https://ikiform.com/blog/form-submissions-to-zapier

Zapier connects to thousands of apps, so it's a quick way to get Ikiform submissions into a CRM, a help desk or an email tool without writing a server. This guide catches the raw delivery, verifies it in a Code step, and only lets real submissions through.

Diagram: How a submission gets from your form to Zapier

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and posts a signed webhook to a Zapier catch hook.
3. A Code step checks the signature, and a Filter step stops anything that isn't a verified submission.
4. Your actions send the fields to a CRM, a help desk, email or a sheet.

Ikiform posts each submission to a Zapier catch hook. A Code step checks the signature before any action runs.

## What you'll build

- A Zap triggered by **Webhooks by Zapier** with the **Catch Raw Hook** event.
- A **Code by Zapier** step that checks Ikiform's signature and splits the fields into plain values.
- A **Filter** step, so only verified submissions reach your actions.

Diagram: The Zap, step by step

1. Catch Raw Hook receives the raw body and headers, and Zapier answers Ikiform 200 right away.
2. The Code step checks the signature and outputs valid, type and one field_ value per form field.
3. The Filter step continues only when valid is true and type is submission.created. Anything else stops there.
4. Your actions map field_email, field_name and the rest.

## Before you start

- An Ikiform form that already receives submissions.
- A Zapier plan that includes webhooks. Webhooks by Zapier isn't available on the Free plan.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Catch Raw Hook or Catch Hook

| Trigger event | What you get | Use it when |
| --- | --- | --- |
| **Catch Raw Hook** | The body as one unparsed string, plus the request headers | You want to verify the signature. This guide uses it |
| **Catch Hook** | The JSON parsed into fields such as `data fields email` | You only need quick mapping and accept that anyone with the URL can start the Zap |

Catch Hook is simpler, but the Zap can't tell an Ikiform delivery from a request someone else made up. If you use it, keep the URL private and treat the data as unverified.

## Set it up

### Step 1: Add the trigger

1. Create a Zap. For the trigger, pick **Webhooks by Zapier** and the event **Catch Raw Hook**.
2. Choose **Continue** until the **Test** tab shows the webhook URL. It looks like `https://hooks.zapier.com/hooks/catch/123456/abcdef/`.
3. Copy the URL.

### Step 2: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste the Zapier webhook URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Zapier", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 3: Catch a real submission

Send one submission from your form. Back in Zapier, choose **Test trigger** and pick the request that arrived. You should see a raw body and the request headers, including the three `webhook-*` headers.

> Zapier's docs don't list the exact names of the raw body and header fields, so pick them from your own test data in the next step rather than typing names by hand.

### Step 4: Verify the signature in a Code step

Add an action: **Code by Zapier**, event **Run Javascript**. Under **Input Data**, add these five entries and map each one from the trigger:

`Input Data`:

```text
secret     whsec_paste_your_signing_secret_here
id         the webhook-id header from the trigger
timestamp  the webhook-timestamp header from the trigger
signature  the webhook-signature header from the trigger
body       the raw body from the trigger
```

Paste this into **Code**:

`Run Javascript`:

```js
const crypto = require("crypto");

const MAX_AGE_SECONDS = 600;

const { secret, id, timestamp, signature, body } = inputData;
const key = Buffer.from(String(secret).replace(/^whsec_/, ""), "base64");
const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest();
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
const matches = String(signature || "")
  .split(" ")
  .some((entry) => {
    const [version, value] = entry.split(",");
    const received = Buffer.from(value || "", "base64");
    return version === "v1" && received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
const valid = Boolean(id && timestamp && age <= MAX_AGE_SECONDS && matches);
const event = valid ? JSON.parse(body) : null;
const fields = event && event.type === "submission.created" ? event.data.fields : {};

const text = (value) => {
  if (value === null || value === undefined) return "";
  if (Array.isArray(value)) return value.map(text).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
};

output = {
  valid,
  type: event ? event.type : "",
  delivery_id: event ? event.id : "",
  form: event && event.data.form ? event.data.form.name : "",
  submission_id: event && event.data.submission_id ? event.data.submission_id : "",
  ...Object.fromEntries(Object.entries(fields).map(([name, value]) => [`field_${name}`, text(value)])),
};
```

Diagram: How the Code step checks an Ikiform signature

1. Read webhook-id, webhook-timestamp and the raw body exactly as received.
2. Reject the request if the timestamp is more than 10 min from now.
3. Base64-decode the part of the secret after whsec_ and use it as the HMAC key.
4. Compute HMAC-SHA256 of id.timestamp.body and base64-encode it.
5. Compare it, in constant time, with each v1 value in webhook-signature. There are two while a secret rotates.
6. If one matches: valid: true, fields split into field_*.
7. If none match: valid: false, the filter stops the zap.

- The HMAC uses the raw body exactly as Ikiform sent it, so the comparison holds byte for byte.
- `valid` is `true` only when a `v1` signature matches and the timestamp is recent. The check allows 10 minutes, a little more than usual, because Zapier can hold a request for a moment before it runs the Zap.
- Each form field becomes its own output, such as `field_email` and `field_message`, ready to map in later steps.

> Zapier passes every Input Data value as a string, and anyone who can edit the Zap can read the secret. Keep the Zap in a folder only your team can open.

### Step 5: Only continue if valid

1. Add a **Filter** step after the Code step.
2. Condition one: `valid` (Boolean) is true.
3. Condition two, with **And**: `type` (Text) exactly matches `submission.created`.

The second condition stops dashboard test events, which carry no fields, from reaching your actions.

### Step 6: Add your actions and publish

Add the actions you want, such as creating a contact or posting a message, and map `field_email`, `field_name` and the rest from the Code step. Then publish the Zap. A Zap that is off answers `404`, which Ikiform retries.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in Zapier's **Zap history**.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event stops at the Filter step. A real submission passes the Filter and runs your actions.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

### Zapier always answers 200

Zapier answers every caught request with `200` before the Zap runs, and the answer can't be changed. Ikiform marks the delivery succeeded as soon as Zapier has it. If a later step fails, Ikiform doesn't retry; replay the run from **Zap history** instead.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `valid` is `false` for every request | Check the five Input Data mappings. `body` must be the raw body, not a parsed field, and `secret` must be this endpoint's `whsec_` secret. |
| `valid` is `false` only sometimes | The run started more than 10 minutes after Ikiform signed it. Raise `MAX_AGE_SECONDS`, or replay the run from Zap history. |
| `404` in the delivery log | The Zap is off or was deleted. Turn it on, then **Retry now** the failed deliveries in Ikiform. |
| The Code step fails with a time limit | Code steps have a short runtime on lower plans. This step only hashes one string and should finish well inside it; check you didn't add network calls. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Avoid duplicate records

A delivery can reach Zapier twice if an earlier attempt timed out on the way. The Code step outputs `delivery_id`, which stays the same across retries. Use it as a unique key in the app you write to, or look it up before you create a record.

## Next steps

| Want to | Read |
| --- | --- |
| Run the same flow without per-task pricing | [Send form submissions to n8n](https://ikiform.com/blog/form-submissions-to-n8n.md) |
| Build it in Make instead | [Send form submissions to Make](https://ikiform.com/blog/form-submissions-to-make.md) |
| See every header and retry rule | [Webhooks](https://ikiform.com/docs/webhooks.md) |

Zapier's own reference: [Trigger Zaps from webhooks](https://help.zapier.com/hc/en-us/articles/8496288690317-Trigger-Zap-workflows-from-webhooks), [JavaScript in Zaps](https://help.zapier.com/hc/en-us/articles/8496310939021-Use-JavaScript-code-in-Zaps) and [Code by Zapier rate limits](https://help.zapier.com/hc/en-us/articles/29971850476173-Code-by-Zapier-rate-limits).

---

Source: https://ikiform.com/blog/form-submissions-to-make

# Send form submissions to Make

> Start a Make scenario from every Ikiform submission with a custom webhook, and add a small relay when you want each delivery verified.

Published 2026-10-23 · Guide, Make · https://ikiform.com/blog/form-submissions-to-make

Make's custom webhooks accept any JSON, so Ikiform can post to them directly. This guide sets that up first, then shows how to add signature checks with a short relay, because Make can't read Ikiform's signature on its own without extra work.

Diagram: Two routes from Ikiform to Make

1. Direct route: Ikiform posts each signed submission straight to the Make custom webhook. Make can't check the signature, so anyone who learns the URL can start the scenario.
2. Verified route: Ikiform posts to a relay. The relay checks the signature, then forwards the same body to Make with the x-make-apikey header.
3. Make's webhook has an API key on the verified route, so it refuses anything without that header.

The direct route skips the relay. The verified route puts a relay between Ikiform and Make.

## Before you start

- An Ikiform form that already receives submissions.
- A Make account. Each run uses operations from your plan.
- For the verified route, somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Pick a route

| Route | Setup | Who can start the scenario |
| --- | --- | --- |
| **Direct** | Paste the Make URL into Ikiform | Anyone who learns the URL |
| **Verified** | Deploy a 30-line relay | Only requests signed with your Ikiform secret |

Start direct to build the scenario. Move to the verified route before the scenario writes anything that matters, such as CRM records or emails.

## Direct route

### Step 1: Add a custom webhook

1. Create a scenario and add the **Webhooks** app with the **Custom webhook** trigger.
2. Choose **Add**, name the webhook, for example `Ikiform`, and save.
3. Copy the address. It looks like `https://hook.eu1.make.com/abc123...`, with the region of your Make account.

### Step 2: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste the Make webhook address into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Make", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 3: Teach Make the data structure

Make learns the fields from the first request it sees. With the webhook module open and waiting, send one real submission from your form, not a dashboard test, because test events have no fields. If you add fields to the form later, open the module and choose **Redetermine data structure**, then send another submission.

### Step 4: Filter and map

Add your next module, such as Google Sheets or Slack. On the link between the two, add a filter where `type` equals `submission.created`. Then map values from `data` > `fields`, such as `email` and `message`.

Turn the scenario on so it runs as soon as data arrives.

> On the direct route, keep the Make address out of public code and screenshots. Make's own API key option for webhooks expects an `x-make-apikey` header, and Ikiform can't add custom headers, so the verified route below is how you lock it down.

## Verified route

The relay checks Ikiform's signature, then forwards the exact same body to Make with an API key header. The scenario stays the same, and Make refuses anything that doesn't carry the key.

### Step 1: Add an API key to the webhook

In Make, open the webhook's settings and add an **API key**. Make then only accepts requests that send that key in the `x-make-apikey` header. Copy the key.

### Step 2: Write the relay

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  MAKE_WEBHOOK_URL: string;
  MAKE_API_KEY: string;
}

function forward(url: string, apiKey: string, payload: string) {
  return fetch(url, {
    method: "POST",
    headers: { "content-type": "application/json", "x-make-apikey": apiKey },
    body: payload,
  });
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await forward(env.MAKE_WEBHOOK_URL, env.MAKE_API_KEY, payload);
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Make rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Make answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/make/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function forward(url: string, apiKey: string, payload: string) {
  return fetch(url, {
    method: "POST",
    headers: { "content-type": "application/json", "x-make-apikey": apiKey },
    body: payload,
  });
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await forward(process.env.MAKE_WEBHOOK_URL!, process.env.MAKE_API_KEY!, payload);
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Make rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Make answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

- The relay forwards `payload`, the raw string it verified, so Make sees exactly what Ikiform sent and the data structure doesn't change.
- A `429` from Make becomes a `503` with Make's `Retry-After`, and any other error becomes a `502`. Ikiform retries both.

### Step 3: Deploy it

### Cloudflare Worker

`Terminal`:

```bash
mkdir ikiform-make && cd ikiform-make
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-make",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put MAKE_WEBHOOK_URL
npx wrangler secret put MAKE_API_KEY
npx wrangler deploy
```

### Next.js

Add `@ikiform/sdk`, save the route handler, and set `IKIFORM_WEBHOOK_SECRET`, `MAKE_WEBHOOK_URL` and `MAKE_API_KEY` in your host's environment variables. Use the production domain, not a protected preview URL.

### Step 4: Point Ikiform at the relay

Open the endpoint in Ikiform, choose **Edit**, and change **URL** to the relay URL. The signing secret stays the same; put it in `IKIFORM_WEBHOOK_SECRET` on the relay.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in Make's scenario **History**.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event runs the scenario and stops at the filter. A real submission continues through it.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What the relay tells Ikiform when Make answers

1. Make accepts the request: the relay answers 204, and Ikiform marks the delivery succeeded.
2. Make is rate limited (429): the relay answers 503 with Make's Retry-After, and Ikiform waits that long before it tries again.
3. Make answers with any other error: the relay answers 502, and Ikiform retries, 8 retries over about 3 d 6 h.

On the verified route. On the direct route, Make answers Ikiform itself.

Without a **Webhook response** module, Make answers `200 Accepted` as soon as the request is queued, before the scenario runs. Ikiform counts that as delivered. If a later module fails, rerun it from Make's history; Ikiform won't retry it. If you add a Webhook response module, place it early, so Make answers within Ikiform's 15 seconds.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400` with `Queue is full` | The scenario is off or slow, and Make's webhook queue filled up. Turn the scenario on; Ikiform retries the deliveries. |
| `502` with `Make answered 4xx` on the verified route | Make refused the request, most often because `MAKE_API_KEY` doesn't match the key on the webhook. Copy it again and update the relay. |
| New form fields don't show up in the mapping | Open the webhook module, choose **Redetermine data structure**, and send a submission that includes the new fields. |
| Endpoint disabled right after you deleted or changed the scenario | Ikiform disables an endpoint at once if it answers `410 Gone`, which can happen when nothing listens on a Make address anymore. Create a new webhook, update the endpoint URL, and turn **Enabled** back on. |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

| Want to | Read |
| --- | --- |
| Add each submission as a sheet row | [Send form submissions to Google Sheets](https://ikiform.com/blog/form-submissions-to-google-sheets.md) |
| Verify inside the workflow tool itself | [Send form submissions to n8n](https://ikiform.com/blog/form-submissions-to-n8n.md) |
| See every header and retry rule | [Webhooks](https://ikiform.com/docs/webhooks.md) |

Make's own reference: [Webhooks](https://help.make.com/webhooks) and the [Webhooks app](https://apps.make.com/gateway).

---

Source: https://ikiform.com/blog/form-submissions-to-pipedream

# Send form submissions to Pipedream

> Trigger a Pipedream workflow from every Ikiform submission, verify the signature in a Node.js step, and pass the fields to any of Pipedream's apps.

Published 2026-10-23 · Guide, Pipedream · https://ikiform.com/blog/form-submissions-to-pipedream

Pipedream sits between no-code and code: each workflow can mix prebuilt app actions with short Node.js steps. That makes it easy to verify Ikiform's signature properly and then hand the fields to Slack, a database or an API.

Diagram: How a submission gets from your form to Pipedream

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and posts a signed webhook to the workflow's HTTP trigger.
3. A Node.js step checks the signature and ends the run for anything else.
4. Later steps send the fields to Slack, Postgres, an API or email.

Ikiform posts to the workflow's HTTP trigger. A Node.js step checks the signature and stops anything else.

## Before you start

- An Ikiform form that already receives submissions.
- A Pipedream account.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

Ikiform caps a delivery at 256 KB and empties `fields` above that, so every delivery fits inside Pipedream's 512 KB request limit.

## Set it up

### Step 1: Add an HTTP trigger

1. Create a workflow and pick the **HTTP / Webhook** trigger.
2. Keep the default response, which answers `200` as soon as the request arrives.
3. Copy the endpoint URL. It looks like `https://eo1a2b3c4d5e6f.m.pipedream.net`.

### Step 2: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste the Pipedream endpoint URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Pipedream", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 3: Store the secret

In Pipedream, open **Settings** > **Environment Variables**, add `IKIFORM_WEBHOOK_SECRET` and paste the `whsec_` secret. Code steps read it from `process.env`.

### Step 4: Verify the signature in a Node.js step

Send one submission from your form so the trigger has an event to test with. Then add a **Node.js** code step, name it `verify`, and paste this:

`verify`:

```js
import crypto from "crypto";

export default defineComponent({
  async run({ steps, $ }) {
    const { headers, body } = steps.trigger.event;
    const raw = JSON.stringify(body);
    const id = headers["webhook-id"];
    const timestamp = headers["webhook-timestamp"];
    const signatures = headers["webhook-signature"] ?? "";
    const age = Math.abs(Date.now() / 1000 - Number(timestamp));
    if (!id || !timestamp || !(age <= 300)) return $.flow.exit("Missing or stale Ikiform webhook headers");

    const key = Buffer.from(process.env.IKIFORM_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");
    const expected = crypto.createHmac("sha256", key).update(`${id}.${timestamp}.${raw}`).digest();
    const valid = signatures.split(" ").some((entry) => {
      const [version, value] = entry.split(",");
      const received = Buffer.from(value ?? "", "base64");
      return version === "v1" && received.length === expected.length && crypto.timingSafeEqual(received, expected);
    });
    if (!valid) return $.flow.exit("Invalid Ikiform webhook signature");
    if (body.type !== "submission.created") return $.flow.exit(`Skipped ${body.type}`);

    return {
      deliveryId: body.id,
      form: body.data.form.name,
      submissionId: body.data.submission_id,
      fields: body.data.fields,
    };
  },
});
```

Diagram: How the verify step checks an Ikiform signature

1. Read webhook-id, webhook-timestamp and the raw body exactly as received.
2. Reject the request if the timestamp is more than 5 minutes from now.
3. Base64-decode the part of the secret after whsec_ and use it as the HMAC key.
4. Compute HMAC-SHA256 of id.timestamp.body and base64-encode it.
5. Compare it, in constant time, with each v1 value in webhook-signature. There are two while a secret rotates.
6. If one matches: return, fields for later steps.
7. If none match: $.flow.exit, no later step runs.

Pipedream parses JSON bodies before your code runs and doesn't keep the original bytes. `JSON.stringify` of the parsed body gives the same bytes back, because Ikiform writes its body as compact JSON with `JSON.stringify` too. Header names arrive in lowercase.

- A missing, stale or wrong signature ends the run with `$.flow.exit`, so no later step runs.
- Test events end the run too, after the signature check, so a dashboard test confirms the secret without touching your apps.
- The step returns the form name, ids and fields for later steps.

### Step 5: Use the fields

Add the actions you want and reference the step's return value:

`References`:

```text
{{steps.verify.$return_value.fields.email}}
{{steps.verify.$return_value.fields.message}}
{{steps.verify.$return_value.form}}
```

Deploy the workflow so it runs on every delivery.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Answer only after the check

With the default response, Pipedream answers `200` before your steps run, so Ikiform counts every delivery as delivered. If you want failed checks to show in Ikiform's delivery log and be retried, set the trigger to return a custom response from the workflow, and call this right after the signature check:

`verify`:

```js
await $.respond({ immediate: true, status: 204 });
```

Diagram: When Pipedream answers Ikiform, with the default and a custom response

1. With the default response, the HTTP trigger answers 200 as soon as the request arrives, and the verify step runs after that. Ikiform counts every delivery as delivered.
2. With a custom response, the trigger waits. The verify step calls $.respond with 204 right after the signature check.
3. If the check fails, the run ends before $.respond, Pipedream answers 400, and Ikiform retries.

> In that mode, a run that ends before `$.respond` answers `400`, which Ikiform retries. Keep the `$.respond` call before any slow step so Ikiform gets its answer within 15 seconds.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in Pipedream's event inspector.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event ends at the verify step with `Skipped endpoint.test`. A real submission runs every step.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| Run ends with **Invalid Ikiform webhook signature** | `IKIFORM_WEBHOOK_SECRET` doesn't belong to this endpoint. Copy it again, or use **Roll secret** and update the variable. |
| Run ends with **Missing or stale Ikiform webhook headers** | The request didn't come from Ikiform, or you replayed an old event by hand. Send a new submission, or **Retry now** the delivery in Ikiform. |
| `429` in the delivery log | Pipedream throttles very high request rates. Ikiform waits and retries. |
| `400 timestamp_too_old` | The signature is more than 5 minutes old. Check the server clock, and don't replay old deliveries by hand; use **Retry now** on the delivery instead, which signs it again. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Avoid duplicate records

Retries reuse the same delivery id. The verify step returns it as `deliveryId`; check it against a data store or a unique column before you create records.

## Next steps

| Want to | Read |
| --- | --- |
| Post each submission to a channel | [Send form submissions to Slack](https://ikiform.com/blog/form-submissions-to-slack.md) |
| Run the check on your own server | [Receiving webhooks](https://ikiform.com/docs/guides/webhook-handlers.md) |
| See every header and retry rule | [Webhooks](https://ikiform.com/docs/webhooks.md) |

Pipedream's own reference: [triggers](https://pipedream.com/docs/workflows/building-workflows/triggers), [Node.js steps](https://pipedream.com/docs/workflows/building-workflows/code/nodejs) and [limits](https://pipedream.com/docs/workflows/limits).

---

Source: https://ikiform.com/blog/form-submissions-to-google-sheets

# Send form submissions to Google Sheets

> Add a row to a Google Sheet for every Ikiform submission, with a verified relay in front of an Apps Script web app, or with n8n or Make.

Published 2026-10-23 · Guide, Google Sheets · https://ikiform.com/blog/form-submissions-to-google-sheets

A spreadsheet is often all a small team needs to track leads or sign-ups. This guide adds one row per Ikiform submission, adds a column when the form gets a new field, and never writes the same submission twice.

Diagram: How a submission gets from your form to Google Sheets

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and posts a signed webhook to the relay.
3. The relay checks the signature, then posts the event with a shared token to the Apps Script web app.
4. Apps Script checks the token and appends a row to the sheet.

The relay verifies Ikiform's signature, then hands the event to an Apps Script web app that owns the sheet.

## Why there's a relay

An Apps Script web app can receive a `POST`, but two things stop Ikiform from posting to it directly:

- `doPost` can read the body but not the request headers, so the script can't check Ikiform's signature.
- Apps Script answers every request to `/exec` with a `302` redirect to `script.googleusercontent.com`. Ikiform doesn't follow redirects and counts that as a failure, so it retries a delivery that already wrote a row. You'd get duplicates.

The relay fixes both. It checks the signature, posts to Apps Script with a shared token, follows the redirect, and answers Ikiform with a clean `204`.

Diagram: Why Ikiform can't post to Apps Script directly

1. Straight to Apps Script: the script writes the row, then answers with a 302 redirect. Ikiform doesn't follow redirects, counts a failure and retries, so the row is written again. The script also can't read the signature headers.
2. Through the relay: the relay checks the signature, posts the event with a shared token, follows the redirect to read the script's answer, and answers Ikiform with 204.

> Prefer no code? [n8n](https://ikiform.com/blog/form-submissions-to-n8n.md) and [Make](https://ikiform.com/blog/form-submissions-to-make.md) both have Google Sheets actions that append a row. Use one of those guides and add the Sheets step after the webhook.

## Before you start

- An Ikiform form that already receives submissions.
- A Google account and a spreadsheet you can edit.
- Somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Set it up

### Step 1: Add the Apps Script

1. Open the spreadsheet and choose **Extensions** > **Apps Script**.
2. Replace the contents of `Code.gs` with the script below and save.

`Code.gs`:

```js
const SHEET_NAME = "Submissions";
const FIXED = ["delivery_id", "submission_id", "created_at", "form"];

function doPost(e) {
  const request = JSON.parse(e.postData.contents);
  const token = PropertiesService.getScriptProperties().getProperty("TOKEN");
  if (!token || request.token !== token) return reply({ ok: false, error: "unauthorized" });
  const event = request.event;
  if (event.type !== "submission.created") return reply({ ok: true, skipped: event.type });

  const lock = LockService.getScriptLock();
  lock.waitLock(10000);
  try {
    const book = SpreadsheetApp.getActiveSpreadsheet();
    const sheet = book.getSheetByName(SHEET_NAME) || book.insertSheet(SHEET_NAME);
    const fields = event.data.fields;
    let header = sheet.getLastRow() > 0 ? sheet.getRange(1, 1, 1, sheet.getLastColumn()).getValues()[0] : [];
    if (header.length === 0) header = FIXED.slice();
    const missing = Object.keys(fields).filter((name) => header.indexOf(name) === -1);
    if (missing.length > 0 || sheet.getLastRow() === 0) {
      header = header.concat(missing);
      sheet.getRange(1, 1, 1, header.length).setValues([header]);
    }

    const rows = sheet.getLastRow() - 1;
    if (rows > 0) {
      const ids = sheet.getRange(2, 1, rows, 1).getValues();
      if (ids.some((row) => row[0] === event.id)) return reply({ ok: true, duplicate: true });
    }

    const fixed = {
      delivery_id: event.id,
      submission_id: event.data.submission_id,
      created_at: event.data.created_at,
      form: event.data.form.name,
    };
    sheet.appendRow(header.map((name) => cell(FIXED.indexOf(name) === -1 ? fields[name] : fixed[name])));
    return reply({ ok: true });
  } finally {
    lock.releaseLock();
  }
}

function cell(value) {
  if (value === null || value === undefined) return "";
  if (Array.isArray(value)) return cell(value.map(String).join(", "));
  if (typeof value === "object") return cell(JSON.stringify(value));
  const text = String(value);
  return /^[=+\-@\t\r]/.test(text) ? `'${text}` : text;
}

function reply(body) {
  return ContentService.createTextOutput(JSON.stringify(body)).setMimeType(ContentService.MimeType.JSON);
}
```

- The first row holds the column names. New fields get a new column at the end.
- Column A is the delivery id. A retry with the same id is skipped, so a row is never written twice.
- Values that start with `=`, `+`, `-` or `@` get a leading `'`, so a visitor can't put a formula in your sheet.
- The script lock stops two deliveries arriving together from writing over each other.

Diagram: How the relay maps an Ikiform submission to sheet row

1. id: dlv_… becomes column A: delivery_id.
2. submission_id becomes submission_id.
3. data.created_at becomes created_at.
4. form.name becomes form.
5. fields.name, email, message becomes one column per field, by name.
6. a new field adds a column at the end is added by the relay.

Column A is checked first, so a retry with the same delivery id writes nothing.

### Step 2: Set the shared token

Make a long random string:

`Terminal`:

```bash
node -e "console.log(crypto.randomUUID() + crypto.randomUUID())"
```

In the Apps Script editor, open **Project Settings**, add a script property named `TOKEN`, and paste the string. The relay sends the same value, and the script refuses anything else.

### Step 3: Deploy it as a web app

1. Choose **Deploy** > **New deployment**, and pick **Web app** as the type.
2. Run it as yourself, so the script can write to your sheet.
3. Give access to anyone, so the relay can call it without a Google sign-in. The token keeps other callers out.
4. Choose **Deploy**, authorize the script, and copy the **Web app** URL ending in `/exec`.

> Saving the script doesn't update a deployment. After an edit, use **Deploy** > **Manage deployments**, edit the deployment and pick a new version. The URL stays the same.

### Step 4: Write the relay

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  APPS_SCRIPT_URL: string;
  SHEETS_TOKEN: string;
}

async function sendToSheet(url: string, token: string, event: WebhookEvent) {
  const response = await fetch(url, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ token, event }),
  });
  if (!response.ok) return response;
  const result = (await response.json().catch(() => null)) as { ok?: boolean; error?: string } | null;
  if (result?.ok) return new Response(null, { status: 204 });
  return new Response(null, { status: result?.error === "unauthorized" ? 401 : 422 });
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await sendToSheet(env.APPS_SCRIPT_URL, env.SHEETS_TOKEN, event);
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Google Sheets rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Google Sheets answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/sheets/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

async function sendToSheet(url: string, token: string, event: WebhookEvent) {
  const response = await fetch(url, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ token, event }),
  });
  if (!response.ok) return response;
  const result = (await response.json().catch(() => null)) as { ok?: boolean; error?: string } | null;
  if (result?.ok) return new Response(null, { status: 204 });
  return new Response(null, { status: result?.error === "unauthorized" ? 401 : 422 });
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await sendToSheet(process.env.APPS_SCRIPT_URL!, process.env.SHEETS_TOKEN!, event);
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Google Sheets rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Google Sheets answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

- `fetch` follows the Apps Script redirect by default and reads the script's JSON answer at the end of it.
- A wrong token or a script error returns an error to Ikiform, which retries. A rate limit becomes a `503` with `Retry-After`.

### Step 5: Deploy the relay

### Cloudflare Worker

`Terminal`:

```bash
mkdir ikiform-sheets && cd ikiform-sheets
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-sheets",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

Set `APPS_SCRIPT_URL` to the `/exec` URL and `SHEETS_TOKEN` to the token, then deploy:

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put APPS_SCRIPT_URL
npx wrangler secret put SHEETS_TOKEN
npx wrangler deploy
```

### Next.js

Add `@ikiform/sdk`, save the route handler, and set `IKIFORM_WEBHOOK_SECRET`, `APPS_SCRIPT_URL` and `SHEETS_TOKEN` in your host's environment variables. Use the production domain, not a protected preview URL.

### Step 6: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste the relay URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Google Sheets", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 7: Add the secret to the relay

Set `IKIFORM_WEBHOOK_SECRET` on the relay to the `whsec_` secret. On Cloudflare, `npx wrangler secret put IKIFORM_WEBHOOK_SECRET` applies it right away.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in the sheet.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event checks the whole chain, signature and token included, without adding a row. A real submission adds a `Submissions` tab on first use, writes the header row, then the data.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Apps Script can take a few seconds to start when it hasn't run for a while. The relay waits for it, and the script holds its lock for at most 10 seconds, which keeps the whole round trip inside Ikiform's 15 seconds in normal use.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `502` with `Google Sheets answered 401` | `SHEETS_TOKEN` on the relay doesn't match the `TOKEN` script property. Copy it again. |
| `502` with `Google Sheets answered 422` | Apps Script returned a sign-in or error page instead of JSON. Check the deployment gives access to anyone, and that `APPS_SCRIPT_URL` ends in `/exec`, not `/dev`. |
| Script changes don't take effect | Edit the existing deployment and pick a new version. Saving the file alone doesn't change what `/exec` runs. |
| Errors under **Executions** in Apps Script | Open the failed run to see the line. A `Lock timeout` means many deliveries arrived at once; Ikiform retries them. |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

| Want to | Read |
| --- | --- |
| Also post each submission to a channel | [Send form submissions to Slack](https://ikiform.com/blog/form-submissions-to-slack.md) |
| Download older submissions as CSV | [Exporting submissions](https://ikiform.com/docs/guides/export.md) |
| See every header and retry rule | [Webhooks](https://ikiform.com/docs/webhooks.md) |

Google's own reference: [Apps Script web apps](https://developers.google.com/apps-script/guides/web), [Content service redirects](https://developers.google.com/apps-script/guides/content), [deployments](https://developers.google.com/apps-script/concepts/deployments), [LockService](https://developers.google.com/apps-script/reference/lock/lock-service) and [quotas](https://developers.google.com/apps-script/guides/services/quotas).

---

Source: https://ikiform.com/blog/form-submissions-to-notion

# Send form submissions to a Notion database

> Turn every Ikiform submission into a page in a Notion database, with a small relay that verifies the signature and calls the Notion API.

Published 2026-10-23 · Guide, Notion · https://ikiform.com/blog/form-submissions-to-notion

A Notion database works well as a lightweight inbox for applications, feedback or leads. Your team can sort, assign and comment on each submission. This guide creates one Notion page per Ikiform submission.

Diagram: How a submission gets from your form to Notion

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and sends a signed webhook to your relay.
3. The relay checks the signature, maps fields to properties and creates a page with the Notion API.
4. Notion answers the relay, and the relay answers Ikiform.

The relay checks Ikiform's signature, then creates a page through the Notion API.

## Why there's a relay

Notion has no inbound webhook URL for databases. New pages are created with an authenticated call to `POST /v1/pages`, with a body in Notion's own shape. Ikiform can't add Notion's headers or send a custom body, so a relay in between does it. It also keeps your Notion token out of Ikiform.

If you'd rather not deploy code, [n8n](https://ikiform.com/blog/form-submissions-to-n8n.md), [Zapier](https://ikiform.com/blog/form-submissions-to-zapier.md) and [Make](https://ikiform.com/blog/form-submissions-to-make.md) all have a Notion action that does the same thing.

## Before you start

- An Ikiform form that already receives submissions.
- A Notion workspace where you're a workspace owner, so you can create a connection.
- Somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app on Vercel or any other host.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Set it up

### Step 1: Create the database

Create a Notion database with these properties. The names must match exactly, including case.

| Property | Type | Filled with |
| --- | --- | --- |
| `Name` | Title | The form's `name` field, or the form name |
| `Email` | Email | The `email` field |
| `Message` | Text | The `message` field |
| `Submitted` | Date | `data.created_at` |
| `Submission ID` | Text | `data.submission_id` |

Every field is also written into the page body as one line each, so fields without a property aren't lost. Add more properties later by extending the `PROPERTIES` map in the relay.

### Step 2: Create a Notion connection

1. Open [app.notion.com/developers/connections](https://app.notion.com/developers/connections) and create a new internal connection for your workspace.
2. Give it the capability to insert content.
3. Copy the token from the **Configuration** tab.

Then open the database in Notion, choose the **•••** menu at the top right, choose **Add connections**, and pick your connection. Without this step the API answers `404 object_not_found`.

### Step 3: Find the data source ID

Since API version 2025-09-03, pages are created under a data source, not a database. In Notion, open the database's **Manage data sources** menu and choose **Copy data source ID**. Or ask the API, using the database ID from the database's URL:

`Terminal`:

```bash
curl https://api.notion.com/v1/databases/$DATABASE_ID \
  -H "Authorization: Bearer $NOTION_TOKEN" \
  -H "Notion-Version: 2026-03-11"
```

`Response`:

```json
{
  "object": "database",
  "id": "2a8e5f3c-0000-0000-0000-000000000000",
  "data_sources": [
    { "id": "1f2c7b9e-0000-0000-0000-000000000000", "name": "Leads" }
  ]
}
```

Use the `id` inside `data_sources`.

### Step 4: Write the relay

Both versions verify the signature with `@ikiform/sdk`, map fields to properties, and ignore `endpoint.test` events so tests don't create pages.

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  NOTION_TOKEN: string;
  NOTION_DATA_SOURCE_ID: string;
}

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

const NOTION_VERSION = "2026-03-11";
const TITLE_FIELD = "name";
const PROPERTIES: Record<string, { property: string; type: "rich_text" | "email" | "url" | "number" | "select" }> = {
  email: { property: "Email", type: "email" },
  message: { property: "Message", type: "rich_text" },
};

function richText(text: string) {
  const characters = Array.from(text);
  const chunks: string[] = [];
  for (let index = 0; index < characters.length && chunks.length < 100; index += 2000) {
    chunks.push(characters.slice(index, index + 2000).join(""));
  }
  return (chunks.length ? chunks : [""]).map((content) => ({ type: "text", text: { content } }));
}

function property(type: string, value: unknown) {
  const text = valueText(value);
  if (type === "email") return { email: text.slice(0, 200) };
  if (type === "url") return { url: text.slice(0, 2000) };
  if (type === "select") return { select: { name: text.replaceAll(",", " ").slice(0, 100) } };
  if (type === "number") {
    const number = Number(value);
    return Number.isFinite(number) ? { number } : null;
  }
  return { rich_text: richText(text) };
}

function toNotion(event: Extract<WebhookEvent, { type: "submission.created" }>, dataSourceId: string) {
  const { form, fields, submission_id, created_at } = event.data;
  const title = fields[TITLE_FIELD] ? valueText(fields[TITLE_FIELD]) : `${form.name} submission`;
  const properties: Record<string, unknown> = {
    Name: { title: richText(title.slice(0, 2000)) },
    Submitted: { date: { start: created_at } },
    "Submission ID": { rich_text: richText(submission_id) },
  };
  for (const [field, target] of Object.entries(PROPERTIES)) {
    if (fields[field] === undefined || fields[field] === "") continue;
    const value = property(target.type, fields[field]);
    if (value) properties[target.property] = value;
  }
  const children = Object.entries(fields)
    .slice(0, 99)
    .map(([name, value]) => ({
      object: "block",
      type: "paragraph",
      paragraph: { rich_text: richText(`${name}: ${valueText(value)}`) },
    }));
  if (event.data.truncated) {
    children.push({
      object: "block",
      type: "paragraph",
      paragraph: { rich_text: richText("The submission was too large to include. Open it in Ikiform.") },
    });
  }
  return { parent: { type: "data_source_id", data_source_id: dataSourceId }, properties, children };
}

async function createPage(event: WebhookEvent, token: string, dataSourceId: string) {
  if (event.type !== "submission.created") return new Response(null, { status: 204 });
  return fetch("https://api.notion.com/v1/pages", {
    method: "POST",
    headers: {
      authorization: `Bearer ${token}`,
      "content-type": "application/json",
      "notion-version": NOTION_VERSION,
    },
    body: JSON.stringify(toNotion(event, dataSourceId)),
  });
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await createPage(event, env.NOTION_TOKEN, env.NOTION_DATA_SOURCE_ID);
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Notion rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Notion answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/notion/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

const NOTION_VERSION = "2026-03-11";
const TITLE_FIELD = "name";
const PROPERTIES: Record<string, { property: string; type: "rich_text" | "email" | "url" | "number" | "select" }> = {
  email: { property: "Email", type: "email" },
  message: { property: "Message", type: "rich_text" },
};

function richText(text: string) {
  const characters = Array.from(text);
  const chunks: string[] = [];
  for (let index = 0; index < characters.length && chunks.length < 100; index += 2000) {
    chunks.push(characters.slice(index, index + 2000).join(""));
  }
  return (chunks.length ? chunks : [""]).map((content) => ({ type: "text", text: { content } }));
}

function property(type: string, value: unknown) {
  const text = valueText(value);
  if (type === "email") return { email: text.slice(0, 200) };
  if (type === "url") return { url: text.slice(0, 2000) };
  if (type === "select") return { select: { name: text.replaceAll(",", " ").slice(0, 100) } };
  if (type === "number") {
    const number = Number(value);
    return Number.isFinite(number) ? { number } : null;
  }
  return { rich_text: richText(text) };
}

function toNotion(event: Extract<WebhookEvent, { type: "submission.created" }>, dataSourceId: string) {
  const { form, fields, submission_id, created_at } = event.data;
  const title = fields[TITLE_FIELD] ? valueText(fields[TITLE_FIELD]) : `${form.name} submission`;
  const properties: Record<string, unknown> = {
    Name: { title: richText(title.slice(0, 2000)) },
    Submitted: { date: { start: created_at } },
    "Submission ID": { rich_text: richText(submission_id) },
  };
  for (const [field, target] of Object.entries(PROPERTIES)) {
    if (fields[field] === undefined || fields[field] === "") continue;
    const value = property(target.type, fields[field]);
    if (value) properties[target.property] = value;
  }
  const children = Object.entries(fields)
    .slice(0, 99)
    .map(([name, value]) => ({
      object: "block",
      type: "paragraph",
      paragraph: { rich_text: richText(`${name}: ${valueText(value)}`) },
    }));
  if (event.data.truncated) {
    children.push({
      object: "block",
      type: "paragraph",
      paragraph: { rich_text: richText("The submission was too large to include. Open it in Ikiform.") },
    });
  }
  return { parent: { type: "data_source_id", data_source_id: dataSourceId }, properties, children };
}

async function createPage(event: WebhookEvent, token: string, dataSourceId: string) {
  if (event.type !== "submission.created") return new Response(null, { status: 204 });
  return fetch("https://api.notion.com/v1/pages", {
    method: "POST",
    headers: {
      authorization: `Bearer ${token}`,
      "content-type": "application/json",
      "notion-version": NOTION_VERSION,
    },
    body: JSON.stringify(toNotion(event, dataSourceId)),
  });
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await createPage(event, process.env.NOTION_TOKEN!, process.env.NOTION_DATA_SOURCE_ID!);
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Notion rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Notion answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

Diagram: How the relay maps an Ikiform submission to Notion page

1. fields.name: Ada becomes Name (title): Ada.
2. fields.email becomes Email (email).
3. fields.message becomes Message (text).
4. data.created_at becomes Submitted (date).
5. submission_id becomes Submission ID (text).
6. every field becomes page body: one line per field.

Without a name field, the title is the form name plus submission.

For the sample submission, the relay sends Notion this body:

`POST /v1/pages`:

```json
{
  "parent": { "type": "data_source_id", "data_source_id": "1f2c7b9e-0000-0000-0000-000000000000" },
  "properties": {
    "Name": { "title": [{ "type": "text", "text": { "content": "Ada" } }] },
    "Submitted": { "date": { "start": "2026-10-23T12:00:00.000Z" } },
    "Submission ID": { "rich_text": [{ "type": "text", "text": { "content": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3" } }] },
    "Email": { "email": "ada@example.com" },
    "Message": { "rich_text": [{ "type": "text", "text": { "content": "Hello" } }] }
  },
  "children": [
    { "object": "block", "type": "paragraph", "paragraph": { "rich_text": [{ "type": "text", "text": { "content": "name: Ada" } }] } }
  ]
}
```

- Notion allows 2,000 characters per text object, so long values are split into several objects.
- `TITLE_FIELD` and `PROPERTIES` decide which form fields go where. A field missing from the submission is skipped.
- Values are sent as plain text objects, so a visitor can't add links or mentions.
- A `429` from Notion becomes a `503` with Notion's `Retry-After`, so Ikiform waits before it tries again. Any other error becomes a `502`, which Ikiform retries.

### Step 5: Deploy it

### Cloudflare Worker

`Terminal`:

```bash
mkdir ikiform-notion && cd ikiform-notion
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

Save the Worker code as `src/index.ts`, then set the route in `wrangler.jsonc`:

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-notion",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

Add the secrets and deploy:

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put NOTION_TOKEN
npx wrangler secret put NOTION_DATA_SOURCE_ID
npx wrangler deploy
```

Your relay URL is `https://hooks.example.com/`.

### Next.js

Add `@ikiform/sdk` to the app, save the route handler, and set `IKIFORM_WEBHOOK_SECRET`, `NOTION_TOKEN` and `NOTION_DATA_SOURCE_ID` in your host's environment variables. Use the production domain as the relay URL, not a protected preview URL.

### Step 6: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste your relay URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Notion leads", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 7: Add the secret to the relay

Set `IKIFORM_WEBHOOK_SECRET` to the `whsec_` secret. On Cloudflare run `npx wrangler secret put IKIFORM_WEBHOOK_SECRET` again. On other hosts, update the variable and redeploy.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in the Notion database.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event returns `204` from the relay and creates nothing. The real submission creates a page with the properties filled in.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What the relay tells Ikiform when Notion answers

1. Notion accepts the request: the relay answers 204, and Ikiform marks the delivery succeeded.
2. Notion is rate limited (429): the relay answers 503 with Notion's Retry-After, and Ikiform waits that long before it tries again.
3. Notion answers with any other error: the relay answers 502, and Ikiform retries, 8 retries over about 3 d 6 h.

Notion allows about 180 requests a minute per connection. A normal form never comes close, and a burst that does gets Notion's `Retry-After` passed back to Ikiform.

> If Notion created the page but its answer took longer than 15 seconds, Ikiform retries and a second page appears. It's rare. The `Submission ID` property makes duplicates easy to spot, and you can filter on it before creating a page if you need strict once-only.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| `502` with `Notion answered 404` | The connection can't see the database. Add it with **•••** then **Add connections**, and check that `NOTION_DATA_SOURCE_ID` is the data source ID, not the database ID. |
| `502` with `Notion answered 400` | A property name or type doesn't match the database. Check the relay's logs for Notion's `validation_error` message, then fix the database or the `PROPERTIES` map. |
| `502` with `Notion answered 401` | The token is wrong or was revoked. Copy it again from the connection's **Configuration** tab. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

- Map more fields: add a `select` property for a topic field, or a `url` property for a website field.
- Send each form to its own database with one Ikiform endpoint and one relay per form.
- Post a message as well: see [Send form submissions to Slack](https://ikiform.com/blog/form-submissions-to-slack.md).

| Notion reference | Link |
| --- | --- |
| Creating a connection | [developers.notion.com](https://developers.notion.com/docs/authorization) |
| Create a page | [developers.notion.com](https://developers.notion.com/reference/post-page) |
| Property values | [developers.notion.com](https://developers.notion.com/reference/page-property-values) |
| Data sources | [developers.notion.com](https://developers.notion.com/docs/upgrade-guide-2025-09-03) |
| Request limits | [developers.notion.com](https://developers.notion.com/reference/request-limits) |

---

Source: https://ikiform.com/blog/form-submissions-to-airtable

# Send form submissions to Airtable

> Add a row to an Airtable table for every Ikiform submission, through a small relay that verifies the signature and calls the Airtable Web API.

Published 2026-10-23 · Guide, Airtable · https://ikiform.com/blog/form-submissions-to-airtable

Airtable is a good home for submissions you want to sort, filter and build views on. This guide adds one record per Ikiform submission, with each form field in its own column.

Diagram: How a submission gets from your form to Airtable

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and sends a signed webhook to your relay.
3. The relay checks the signature, maps fields to columns and creates a record with the Airtable Web API.
4. Airtable answers the relay, and the relay answers Ikiform.

The relay checks Ikiform's signature, then creates a record through the Airtable Web API.

## Two ways to connect

|   | Relay and Web API | Automation webhook trigger |
| --- | --- | --- |
| Checks Ikiform's signature | Yes | No. Anyone with the URL can add rows |
| Maps nested fields | Yes, in code | Limited. Ikiform's fields sit under `data.fields` |
| Size limit | Ikiform's 256 KB | 100 KB per request |
| Counts against automation runs | No | Yes |

This guide uses the relay. The automation option is covered [at the end](#automation-trigger), with its trade-offs.

## Before you start

- An Ikiform form that already receives submissions.
- An Airtable base where you're at least an editor.
- Somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app on Vercel or any other host.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Set it up

### Step 1: Create the table

Create a table called `Submissions` with these fields. Names must match exactly.

| Field | Type | Filled with |
| --- | --- | --- |
| `Submission ID` | Single line text | `data.submission_id` |
| `Form` | Single line text | The form's name |
| `Submitted` | Date, with time | `data.created_at` |
| `Name` | Single line text | The `name` field |
| `Email` | Email | The `email` field |
| `Message` | Long text | The `message` field |

The relay only sends columns listed in its `COLUMNS` map, because Airtable refuses unknown field names. Add a column in Airtable, then add a line to the map.

### Step 2: Create a personal access token

1. Open [airtable.com/create/tokens](https://airtable.com/create/tokens) and choose **Create new token**.
2. Add the scope `data.records:write`.
3. Under access, add the base that holds the table.
4. Create the token and copy it.

The base ID is the part of the base's URL that starts with `app`. Check the token and table with one request:

`Terminal`:

```bash
curl https://api.airtable.com/v0/$AIRTABLE_BASE_ID/Submissions \
  -H "Authorization: Bearer $AIRTABLE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"fields":{"Name":"Test from the terminal"}}],"typecast":true}'
```

A JSON answer with a `records` array means it worked. Delete the test row.

### Step 3: Write the relay

Both versions verify the signature with `@ikiform/sdk`, map fields to columns, and ignore `endpoint.test` events so tests don't add rows.

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  AIRTABLE_TOKEN: string;
  AIRTABLE_BASE_ID: string;
  AIRTABLE_TABLE: string;
}

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

const COLUMNS: Record<string, string> = {
  name: "Name",
  email: "Email",
  message: "Message",
};

function toAirtable(event: Extract<WebhookEvent, { type: "submission.created" }>) {
  const { fields, submission_id, created_at, form } = event.data;
  const record: Record<string, string> = {
    "Submission ID": submission_id,
    Form: form.name,
    Submitted: created_at,
  };
  for (const [field, column] of Object.entries(COLUMNS)) {
    if (fields[field] !== undefined) record[column] = valueText(fields[field]).slice(0, 100000);
  }
  return { records: [{ fields: record }], typecast: true };
}

async function createRecord(event: WebhookEvent, token: string, baseId: string, table: string) {
  if (event.type !== "submission.created") return new Response(null, { status: 204 });
  return fetch(`https://api.airtable.com/v0/${baseId}/${encodeURIComponent(table)}`, {
    method: "POST",
    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
    body: JSON.stringify(toAirtable(event)),
  });
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await createRecord(event, env.AIRTABLE_TOKEN, env.AIRTABLE_BASE_ID, env.AIRTABLE_TABLE);
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Airtable rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Airtable answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/airtable/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

const COLUMNS: Record<string, string> = {
  name: "Name",
  email: "Email",
  message: "Message",
};

function toAirtable(event: Extract<WebhookEvent, { type: "submission.created" }>) {
  const { fields, submission_id, created_at, form } = event.data;
  const record: Record<string, string> = {
    "Submission ID": submission_id,
    Form: form.name,
    Submitted: created_at,
  };
  for (const [field, column] of Object.entries(COLUMNS)) {
    if (fields[field] !== undefined) record[column] = valueText(fields[field]).slice(0, 100000);
  }
  return { records: [{ fields: record }], typecast: true };
}

async function createRecord(event: WebhookEvent, token: string, baseId: string, table: string) {
  if (event.type !== "submission.created") return new Response(null, { status: 204 });
  return fetch(`https://api.airtable.com/v0/${baseId}/${encodeURIComponent(table)}`, {
    method: "POST",
    headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
    body: JSON.stringify(toAirtable(event)),
  });
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await createRecord(event, process.env.AIRTABLE_TOKEN!, process.env.AIRTABLE_BASE_ID!, process.env.AIRTABLE_TABLE!);
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Airtable rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Airtable answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

Diagram: How the relay maps an Ikiform submission to Airtable record

1. submission_id becomes Submission ID.
2. form.name becomes Form.
3. data.created_at becomes Submitted.
4. fields.name becomes Name.
5. fields.email becomes Email.
6. fields.message becomes Message.

Only columns in the relay's COLUMNS map are sent. Airtable refuses unknown field names.

For the sample submission, the relay sends Airtable this body:

`POST /v0/{baseId}/Submissions`:

```json
{
  "records": [
    {
      "fields": {
        "Submission ID": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
        "Form": "Contact",
        "Submitted": "2026-10-23T12:00:00.000Z",
        "Name": "Ada",
        "Email": "ada@example.com",
        "Message": "Hello"
      }
    }
  ],
  "typecast": true
}
```

- `typecast: true` lets Airtable turn text into dates, numbers and select options, and add new select options when needed.
- Arrays, such as a group of checkboxes, are joined with a comma and a space.
- A `429` from Airtable becomes a `503` with a 30 second `Retry-After`, matching Airtable's 30 second pause. Any other error becomes a `502`, which Ikiform retries.

### Step 4: Deploy it

### Cloudflare Worker

`Terminal`:

```bash
mkdir ikiform-airtable && cd ikiform-airtable
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

Save the Worker code as `src/index.ts`, then set the route in `wrangler.jsonc`:

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-airtable",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

Add the secrets and deploy. Set `AIRTABLE_TABLE` to `Submissions`, or to the table's ID:

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put AIRTABLE_TOKEN
npx wrangler secret put AIRTABLE_BASE_ID
npx wrangler secret put AIRTABLE_TABLE
npx wrangler deploy
```

Your relay URL is `https://hooks.example.com/`.

### Next.js

Add `@ikiform/sdk` to the app, save the route handler, and set `IKIFORM_WEBHOOK_SECRET`, `AIRTABLE_TOKEN`, `AIRTABLE_BASE_ID` and `AIRTABLE_TABLE` in your host's environment variables. Use the production domain as the relay URL.

### Step 5: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste your relay URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Airtable", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 6: Add the secret to the relay

Set `IKIFORM_WEBHOOK_SECRET` to the `whsec_` secret. On Cloudflare run `npx wrangler secret put IKIFORM_WEBHOOK_SECRET` again. On other hosts, update the variable and redeploy.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in the Airtable table.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event returns `204` from the relay and adds nothing. The real submission adds a row.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What the relay tells Ikiform when Airtable answers

1. Airtable accepts the request: the relay answers 204, and Ikiform marks the delivery succeeded.
2. Airtable is rate limited (429): the relay answers 503 with Retry-After (retry-after: 30), and Ikiform waits that long before it tries again.
3. Airtable answers with any other error: the relay answers 502, and Ikiform retries, 8 retries over about 3 d 6 h.

Airtable allows 5 requests a second per base. Over that it answers `429` and refuses requests for 30 seconds. The relay passes that back to Ikiform, so the row arrives a little later rather than not at all.

> If Airtable created the row but answered after Ikiform's 15 second limit, Ikiform retries and a second row appears. It's rare, and the `Submission ID` column makes duplicates easy to find.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| `502` with `Airtable answered 422` | A column in `COLUMNS` doesn't exist in the table, or a value can't be converted. The relay's logs show Airtable's error, such as `UNKNOWN_FIELD_NAME`. |
| `502` with `Airtable answered 403` or `404` | The token lacks `data.records:write`, can't access this base, or the base ID or table name is wrong. |
| `502` with `Airtable answered 401` | The token is wrong or expired. Create a new one. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Without a relay: the automation webhook trigger

Airtable automations can start with **When webhook received**, which gives you a URL that accepts JSON. You can paste it straight into an Ikiform endpoint, because the trigger takes any JSON object. Know the trade-offs first:

- It can't check Ikiform's signature. Anyone who learns the URL can start the automation, so keep it private.
- Requests are limited to 100 KB and 5 a second, and every run counts toward your plan's automation runs.
- Ikiform's fields are nested under `data.fields`. Picking nested values in later steps is limited, so you may need a **Run a script** action that reads the body and sets the fields.
- You have to send a sample request, then choose **Run test**, before Airtable knows the body's shape. Send a real submission for that, not the dashboard test, which has no fields.

## Next steps

- Map more fields by adding columns and lines in `COLUMNS`.
- Build an interface or a kanban view grouped by a status field your team updates.
- Post each new row to a channel too: see [Send form submissions to Slack](https://ikiform.com/blog/form-submissions-to-slack.md).

| Airtable reference | Link |
| --- | --- |
| Personal access tokens | [airtable.com](https://airtable.com/developers/web/guides/personal-access-tokens) |
| Create records | [airtable.com](https://airtable.com/developers/web/api/create-records) |
| Rate limits | [airtable.com](https://airtable.com/developers/web/api/rate-limits) |
| When webhook received | [support.airtable.com](https://support.airtable.com/docs/when-webhook-received-trigger) |

---

Source: https://ikiform.com/blog/form-submissions-to-telegram

# Send form submissions to Telegram

> Get every Ikiform submission as a Telegram message from your own bot, through a small relay that verifies the signature and calls the Bot API.

Published 2026-10-23 · Guide, Telegram · https://ikiform.com/blog/form-submissions-to-telegram

A Telegram bot is a quick way to get new submissions on your phone, in a private chat or in a group with your team. This guide creates a bot, finds the chat to post in, and sends each Ikiform submission there as a formatted message.

Diagram: How a submission gets from your form to Telegram

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and sends a signed webhook to your relay.
3. The relay checks the signature, builds an HTML message and calls sendMessage with your bot's token.
4. Telegram answers the relay, and the relay answers Ikiform.

Ikiform signs the delivery. The relay checks it and calls the Telegram Bot API with your bot's token.

## Why there's a relay

Telegram has no incoming webhook URL for a chat. A bot sends messages by calling `sendMessage` with a `chat_id` and a `text`, and the bot token sits in the URL. Ikiform's submission event has neither field, and the token must never be part of a URL you hand to another service.

> Ikiform sends its own JSON shape to every endpoint and can't send a custom or templated body. Telegram expects its own shape, so pasting the Telegram URL straight into Ikiform doesn't work. A small relay in between verifies the signature and reformats the message.

If you'd rather not deploy code, [n8n](https://ikiform.com/blog/form-submissions-to-n8n.md), [Zapier](https://ikiform.com/blog/form-submissions-to-zapier.md) and [Make](https://ikiform.com/blog/form-submissions-to-make.md) all have Telegram actions that use the same bot token and chat id.

## Before you start

- An Ikiform form that already receives submissions.
- A Telegram account, on the phone or desktop app.
- Somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app on Vercel or any other host.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Set it up

### Step 1: Create a bot

1. In Telegram, open a chat with [@BotFather](https://t.me/BotFather) and send `/newbot`.
2. Give the bot a display name, then a username that ends in `bot`, such as `acme_leads_bot`.
3. BotFather replies with a token like `110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw`. Keep it secret. If it leaks, send `/token` to BotFather to get a new one.

### Step 2: Find the chat id

Decide where messages go. For yourself, open the bot and press **Start**. For a team, add the bot to a group and send any message in the group. Then ask Telegram for the bot's recent updates:

`Terminal`:

```bash
curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates"
```

`Response`:

```json
{
  "ok": true,
  "result": [
    {
      "update_id": 100000001,
      "message": {
        "message_id": 1,
        "chat": { "id": -1001234567890, "title": "Leads", "type": "supergroup" },
        "text": "hello"
      }
    }
  ]
}
```

Copy `message.chat.id`. A private chat has a positive id; a group's id is negative, so keep the minus sign. Updates are kept for 24 hours, so send a fresh message if the list is empty.

> `getUpdates` returns nothing while the bot has its own webhook set. Use a bot that only sends messages, or read the chat id from your existing webhook handler.

Check the bot can post there:

`Terminal`:

```bash
curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"-1001234567890","text":"Hello from the terminal"}'
```

### Step 3: Write the relay

Pick the platform you already use. Both versions verify the signature with `@ikiform/sdk`, build an HTML message, and turn Telegram errors into answers Ikiform retries.

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  TELEGRAM_BOT_TOKEN: string;
  TELEGRAM_CHAT_ID: string;
}

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function escape(text: string) {
  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function toTelegram(event: WebhookEvent) {
  if (event.type === "endpoint.test") return "Ikiform test event received. Submissions will appear here.";
  const { form, fields, submission_id, truncated } = event.data;
  const head = `<b>${escape(clip(`New submission: ${form.name}`, 200))}</b>`;
  const foot = truncated ? "Too large to show here. Open it in Ikiform." : `<code>${submission_id}</code>`;
  const entries = Object.entries(fields);
  let text = head;
  let shown = 0;
  for (const [name, value] of entries) {
    const line = `\n\n<b>${escape(clip(name, 100))}</b>\n${escape(clip(valueText(value), 1000))}`;
    if (text.length + line.length + foot.length + 40 > 4000) break;
    text += line;
    shown += 1;
  }
  const more = entries.length - shown;
  if (more > 0) text += `\n\n${more} more ${more === 1 ? "field" : "fields"} in Ikiform.`;
  return `${text}\n\n${foot}`;
}

async function sendTelegram(token: string, chatId: string, text: string) {
  const response = await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ chat_id: chatId, text, parse_mode: "HTML", link_preview_options: { is_disabled: true } }),
  });
  if (response.status !== 429) return response;
  const body = (await response.json().catch(() => ({}))) as { parameters?: { retry_after?: number } };
  const retryAfter = String(body.parameters?.retry_after ?? 30);
  return new Response(null, { status: 429, headers: { "retry-after": retryAfter } });
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await sendTelegram(env.TELEGRAM_BOT_TOKEN, env.TELEGRAM_CHAT_ID, toTelegram(event));
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Telegram rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Telegram answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/telegram/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function escape(text: string) {
  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function toTelegram(event: WebhookEvent) {
  if (event.type === "endpoint.test") return "Ikiform test event received. Submissions will appear here.";
  const { form, fields, submission_id, truncated } = event.data;
  const head = `<b>${escape(clip(`New submission: ${form.name}`, 200))}</b>`;
  const foot = truncated ? "Too large to show here. Open it in Ikiform." : `<code>${submission_id}</code>`;
  const entries = Object.entries(fields);
  let text = head;
  let shown = 0;
  for (const [name, value] of entries) {
    const line = `\n\n<b>${escape(clip(name, 100))}</b>\n${escape(clip(valueText(value), 1000))}`;
    if (text.length + line.length + foot.length + 40 > 4000) break;
    text += line;
    shown += 1;
  }
  const more = entries.length - shown;
  if (more > 0) text += `\n\n${more} more ${more === 1 ? "field" : "fields"} in Ikiform.`;
  return `${text}\n\n${foot}`;
}

async function sendTelegram(token: string, chatId: string, text: string) {
  const response = await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ chat_id: chatId, text, parse_mode: "HTML", link_preview_options: { is_disabled: true } }),
  });
  if (response.status !== 429) return response;
  const body = (await response.json().catch(() => ({}))) as { parameters?: { retry_after?: number } };
  const retryAfter = String(body.parameters?.retry_after ?? 30);
  return new Response(null, { status: 429, headers: { "retry-after": retryAfter } });
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await sendTelegram(process.env.TELEGRAM_BOT_TOKEN!, process.env.TELEGRAM_CHAT_ID!, toTelegram(event));
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Telegram rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Telegram answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

Diagram: How the relay maps an Ikiform submission to Telegram message

1. form.name: Contact becomes bold line: New submission: Contact.
2. fields.name: Ada becomes bold name, then Ada.
3. fields.email: ada@example.com becomes bold email, then ada@example.com.
4. fields.message: Hello becomes bold message, then Hello.
5. submission_id becomes code line: sub_….

One text message with parse_mode HTML, up to 4,096 characters.

For the sample submission above, the relay sends this text with `parse_mode` set to `HTML`:

`Telegram message`:

```html
<b>New submission: Contact</b>

<b>name</b>
Ada

<b>email</b>
ada@example.com

<b>message</b>
Hello

<code>sub_01k7v2c9t3e8m5q4x6z0a1b2c3</code>
```

- Telegram's HTML mode needs `&`, `<` and `>` escaped outside tags. The relay escapes every value, so a visitor can't add tags or break the message.
- A message can be 4,096 characters. The relay cuts long values and lists how many fields it left out.
- Link previews are off, so a URL in a message field doesn't expand into a card.
- When Telegram's flood control answers `429`, the wait is in the JSON body as `parameters.retry_after`. The relay passes it to Ikiform as a `503` with `Retry-After`. Any other Telegram error becomes a `502`, which Ikiform retries.

### Step 4: Deploy it

### Cloudflare Worker

`Terminal`:

```bash
mkdir ikiform-telegram && cd ikiform-telegram
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

Save the Worker code as `src/index.ts`, then set the route in `wrangler.jsonc`:

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-telegram",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

Add the secrets and deploy:

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put TELEGRAM_BOT_TOKEN
npx wrangler secret put TELEGRAM_CHAT_ID
npx wrangler deploy
```

Your relay URL is `https://hooks.example.com/`.

### Next.js

Add `@ikiform/sdk` to the app, save the route handler, and set `IKIFORM_WEBHOOK_SECRET`, `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` in your host's environment variables. On Vercel the relay URL is `https://your-app.vercel.app/api/ikiform/telegram`. Use the production domain: Vercel's deployment protection blocks requests to protected preview URLs.

### Step 5: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste your relay URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Telegram leads group", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 6: Add the secret to the relay

Set `IKIFORM_WEBHOOK_SECRET` to the `whsec_` secret. On Cloudflare run `npx wrangler secret put IKIFORM_WEBHOOK_SECRET` again; it takes effect right away. On Vercel, update the variable and redeploy.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in Telegram.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event sends a short line to the chat. A real submission sends the full message, with the submission id at the bottom.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What the relay tells Ikiform when Telegram answers

1. Telegram accepts the request: the relay answers 204, and Ikiform marks the delivery succeeded.
2. Telegram is rate limited (429): the relay answers 503 with Retry-After (retry_after from body), and Ikiform waits that long before it tries again.
3. Telegram answers with any other error: the relay answers 502, and Ikiform retries, 8 retries over about 3 d 6 h.

Telegram allows about one message per second in a chat and 20 a minute in a group. A burst of submissions can hit that, and the relay passes Telegram's wait time back to Ikiform, so the extra messages arrive a little later rather than not at all.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| `502` with `Telegram answered 400` | Usually `chat not found` or a wrong chat id. Check `TELEGRAM_CHAT_ID`, including the minus sign for groups. If a group was upgraded to a supergroup, Telegram's error includes `migrate_to_chat_id`; use that id instead. |
| `502` with `Telegram answered 401` or `404` | The bot token is wrong or was replaced with `/token`. Update `TELEGRAM_BOT_TOKEN`. |
| `502` with `Telegram answered 403` | The bot can't post in that chat. It was removed from the group, or the user blocked it or never pressed **Start**. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| The same submission arrives twice | A retry after a slow or failed answer. Every retry carries the same `webhook-id`, so skip ids you've already handled. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

- Post into one topic of a forum group by adding `message_thread_id` to the `sendMessage` body.
- Send each form to a different chat: deploy the relay once per chat, or read the chat id from a map keyed by `event.data.form.id`.
- Skip duplicates by storing the `webhook-id` header, as in [Receiving webhooks](https://ikiform.com/docs/guides/webhook-handlers.md#duplicates).

| Telegram reference | Link |
| --- | --- |
| `sendMessage` | [core.telegram.org](https://core.telegram.org/bots/api#sendmessage) |
| HTML formatting | [core.telegram.org](https://core.telegram.org/bots/api#html-style) |
| `getUpdates` | [core.telegram.org](https://core.telegram.org/bots/api#getupdates) |
| BotFather | [core.telegram.org](https://core.telegram.org/bots/features#botfather) |
| Rate limits | [core.telegram.org](https://core.telegram.org/bots/faq#my-bot-is-hitting-limits-how-do-i-avoid-this) |

---

Source: https://ikiform.com/blog/form-submissions-to-microsoft-teams

# Send form submissions to Microsoft Teams

> Post every Ikiform submission to a Teams channel as an Adaptive Card, using the Workflows app and a small relay that verifies the signature.

Published 2026-10-23 · Guide, Microsoft Teams · https://ikiform.com/blog/form-submissions-to-microsoft-teams

If your team lives in Microsoft Teams, new leads and requests belong in a channel there. This guide posts each Ikiform submission to a channel as an Adaptive Card, with one row per field.

Diagram: How a submission gets from your form to Teams

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and sends a signed webhook to your relay.
3. The relay checks the signature, builds an Adaptive Card and posts it to the Teams workflow.
4. Teams answers the relay, and the relay answers Ikiform.

Ikiform signs the delivery. The relay checks it, builds an Adaptive Card, and posts it to a Teams workflow.

## Office 365 connectors are gone

Older guides use an **Incoming Webhook** connector with a `webhook.office.com` URL. Microsoft retired Office 365 connectors in Teams, and they stopped working in May 2026. Workflow URLs on `logic.azure.com` stopped working too. Today the way in is a webhook from the **Workflows** app, which runs on Power Automate.

## Why there's a relay

The Workflows template expects a message with an Adaptive Card in its `attachments`. Ikiform sends a submission event shaped as `{ "type": ..., "data": ... }`, which the template can't turn into a card.

> Ikiform sends its own JSON shape to every endpoint and can't send a custom or templated body. Teams expects its own shape, so pasting the Teams URL straight into Ikiform doesn't work. A small relay in between verifies the signature and reformats the message.

If you'd rather not deploy code, [n8n](https://ikiform.com/blog/form-submissions-to-n8n.md), [Zapier](https://ikiform.com/blog/form-submissions-to-zapier.md) and [Make](https://ikiform.com/blog/form-submissions-to-make.md) can post to Teams with their own Microsoft Teams actions. If you know Power Automate well, you can also build your own flow that parses Ikiform's JSON; it won't check the signature, though.

## Before you start

- An Ikiform form that already receives submissions.
- A Microsoft 365 account with Teams and permission to add workflows to the channel.
- Somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app on Vercel or any other host.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Set it up

### Step 1: Create a Teams workflow webhook

1. In Teams, open the channel, choose **More options** (**⋯**) next to its name, then **Workflows**.
2. Pick the template **Send webhook alerts to a channel**.
3. Name the workflow, sign in if asked, then pick the team and channel.
4. Save the workflow and copy the webhook URL it shows.

The URL is long, often over 255 characters, and its host ends in `environment.api.powerplatform.com`. Check it works before going further:

`Terminal`:

```bash
curl -X POST "$TEAMS_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"type":"message","attachments":[{"contentType":"application/vnd.microsoft.card.adaptive","contentUrl":null,"content":{"type":"AdaptiveCard","version":"1.4","body":[{"type":"TextBlock","text":"Hello from the terminal"}]}}]}'
```

A card shows up in the channel, posted by the Workflows bot. Treat the URL as a secret: with the default settings, anyone who has it can post to that channel.

> Keep the trigger's **Who can trigger the flow** setting on **Anyone**. The relay can't sign in to Microsoft, and the URL stays private inside the relay.

### Step 2: Write the relay

Pick the platform you already use. Both versions verify the signature with `@ikiform/sdk`, build the card, and turn Teams errors into answers Ikiform retries.

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  TEAMS_WEBHOOK_URL: string;
}

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function bytes(text: string) {
  return new TextEncoder().encode(text).length;
}

function card(body: unknown[]) {
  return {
    type: "message",
    attachments: [
      {
        contentType: "application/vnd.microsoft.card.adaptive",
        contentUrl: null,
        content: {
          $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
          type: "AdaptiveCard",
          version: "1.4",
          body,
        },
      },
    ],
  };
}

function toTeams(event: WebhookEvent) {
  if (event.type === "endpoint.test") {
    return card([{ type: "TextBlock", text: "Ikiform test event received. Submissions will appear here.", wrap: true }]);
  }
  const { form, fields, submission_id, truncated } = event.data;
  const facts: { title: string; value: string }[] = [];
  let budget = 20_000;
  for (const [name, value] of Object.entries(fields)) {
    const fact = { title: clip(name, 100), value: clip(valueText(value), 1000) };
    const size = bytes(fact.title) + bytes(fact.value);
    if (size > budget) break;
    budget -= size;
    facts.push(fact);
  }
  const more = Object.keys(fields).length - facts.length;
  return card([
    { type: "TextBlock", text: clip(`New submission: ${form.name}`, 200), weight: "Bolder", size: "Medium", wrap: true },
    { type: "FactSet", facts },
    ...(more > 0 ? [{ type: "TextBlock", text: `${more} more fields in Ikiform.`, wrap: true }] : []),
    {
      type: "TextBlock",
      text: truncated ? "Too large to show here. Open it in Ikiform." : submission_id,
      isSubtle: true,
      size: "Small",
      wrap: true,
    },
  ]);
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await fetch(env.TEAMS_WEBHOOK_URL, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(toTeams(event)),
    });
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Teams rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Teams answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/teams/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function bytes(text: string) {
  return new TextEncoder().encode(text).length;
}

function card(body: unknown[]) {
  return {
    type: "message",
    attachments: [
      {
        contentType: "application/vnd.microsoft.card.adaptive",
        contentUrl: null,
        content: {
          $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
          type: "AdaptiveCard",
          version: "1.4",
          body,
        },
      },
    ],
  };
}

function toTeams(event: WebhookEvent) {
  if (event.type === "endpoint.test") {
    return card([{ type: "TextBlock", text: "Ikiform test event received. Submissions will appear here.", wrap: true }]);
  }
  const { form, fields, submission_id, truncated } = event.data;
  const facts: { title: string; value: string }[] = [];
  let budget = 20_000;
  for (const [name, value] of Object.entries(fields)) {
    const fact = { title: clip(name, 100), value: clip(valueText(value), 1000) };
    const size = bytes(fact.title) + bytes(fact.value);
    if (size > budget) break;
    budget -= size;
    facts.push(fact);
  }
  const more = Object.keys(fields).length - facts.length;
  return card([
    { type: "TextBlock", text: clip(`New submission: ${form.name}`, 200), weight: "Bolder", size: "Medium", wrap: true },
    { type: "FactSet", facts },
    ...(more > 0 ? [{ type: "TextBlock", text: `${more} more fields in Ikiform.`, wrap: true }] : []),
    {
      type: "TextBlock",
      text: truncated ? "Too large to show here. Open it in Ikiform." : submission_id,
      isSubtle: true,
      size: "Small",
      wrap: true,
    },
  ]);
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await fetch(process.env.TEAMS_WEBHOOK_URL!, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(toTeams(event)),
  });
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Teams rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Teams answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

Diagram: How the relay maps an Ikiform submission to Adaptive Card

1. form.name: Contact becomes TextBlock: New submission: Contact.
2. fields.name: Ada becomes FactSet fact: name / Ada.
3. fields.email: ada@example.com becomes FactSet fact: email / ada@example.com.
4. fields.message: Hello becomes FactSet fact: message / Hello.
5. submission_id becomes small subtle TextBlock: sub_….

The card is Adaptive Card 1.4, wrapped in a message attachment.

For the sample submission above, the relay posts this to the workflow:

`Teams message`:

```json
{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "contentUrl": null,
      "content": {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
          { "type": "TextBlock", "text": "New submission: Contact", "weight": "Bolder", "size": "Medium", "wrap": true },
          {
            "type": "FactSet",
            "facts": [
              { "title": "name", "value": "Ada" },
              { "title": "email", "value": "ada@example.com" },
              { "title": "message", "value": "Hello" }
            ]
          },
          { "type": "TextBlock", "text": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3", "isSubtle": true, "size": "Small", "wrap": true }
        ]
      }
    }
  ]
}
```

- Teams renders Adaptive Cards up to version 1.6. The relay uses 1.4, which works on desktop, web and mobile.
- A Teams message can be about 28 KB. The relay cuts long values and stops adding fields at about 20 KB, then says how many it left out.
- A `429` becomes a `503` with the same `Retry-After`, so Ikiform waits before it tries again. Any other error becomes a `502`, which Ikiform retries.

### Step 3: Deploy it

### Cloudflare Worker

`Terminal`:

```bash
mkdir ikiform-teams && cd ikiform-teams
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

Save the Worker code as `src/index.ts`, then set the route in `wrangler.jsonc`:

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-teams",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

Add both secrets and deploy:

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put TEAMS_WEBHOOK_URL
npx wrangler deploy
```

Your relay URL is `https://hooks.example.com/`.

### Next.js

Add `@ikiform/sdk` to the app, save the route handler, and set `IKIFORM_WEBHOOK_SECRET` and `TEAMS_WEBHOOK_URL` in your host's environment variables. On Vercel the relay URL is `https://your-app.vercel.app/api/ikiform/teams`. Use the production domain: Vercel's deployment protection blocks requests to protected preview URLs.

### Step 4: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste your relay URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Teams Sales channel", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 5: Add the secret to the relay

Set `IKIFORM_WEBHOOK_SECRET` to the `whsec_` secret. On Cloudflare run `npx wrangler secret put IKIFORM_WEBHOOK_SECRET` again; it takes effect right away. On Vercel, update the variable and redeploy.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in Teams.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event posts a one-line card. A real submission posts the full card. If nothing shows up but the delivery succeeded, open the workflow's run history in the Workflows app; the workflow accepts the request first and posts the card a moment later.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What the relay tells Ikiform when Teams answers

1. Teams accepts the request: the relay answers 204, and Ikiform marks the delivery succeeded.
2. Teams is rate limited (429): the relay answers 503 with Teams's Retry-After, and Ikiform waits that long before it tries again.
3. Teams answers with any other error: the relay answers 502, and Ikiform retries, 8 retries over about 3 d 6 h.

Teams throttles a webhook that gets more than about 4 requests a second. The relay passes the `Retry-After` back to Ikiform, so a burst of submissions arrives a little later rather than not at all.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| `502` with `Teams answered 400` | The workflow refused the body. Check that `TEAMS_WEBHOOK_URL` came from the **Send webhook alerts to a channel** template and wasn't cut off when you copied it. |
| `502` with `Teams answered 401` or `403` | The trigger only accepts signed-in users. Set **Who can trigger the flow** to **Anyone**. |
| `502` with `Teams answered 404` | The workflow was deleted or turned off, or the URL is an old `webhook.office.com` or `logic.azure.com` one. Create a new workflow and update `TEAMS_WEBHOOK_URL`. |
| The delivery succeeds but no card appears | Open the workflow's run history. A failed run usually means the flow's owner lost access to the channel. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| The same submission arrives twice | A retry after a slow or failed answer. Every retry carries the same `webhook-id`, so skip ids you've already handled. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

- Send each form to its own channel: add one workflow per channel and one Ikiform endpoint per form. Pro allows 3 endpoints.
- Add an `Action.OpenUrl` button to the card that links to the submission in your own admin, using `data.submission_id`.
- Skip duplicates by storing the `webhook-id` header, as in [Receiving webhooks](https://ikiform.com/docs/guides/webhook-handlers.md#duplicates).

| Microsoft reference | Link |
| --- | --- |
| Create incoming webhooks with Workflows | [learn.microsoft.com](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook) |
| Connectors retirement | [devblogs.microsoft.com](https://devblogs.microsoft.com/microsoft365dev/retirement-of-office-365-connectors-within-microsoft-teams/) |
| Card reference | [learn.microsoft.com](https://learn.microsoft.com/en-us/microsoftteams/platform/task-modules-and-cards/cards/cards-reference) |
| Adaptive Cards | [adaptivecards.io](https://adaptivecards.io/explorer/) |

---

Source: https://ikiform.com/blog/form-submissions-to-google-chat

# Send form submissions to Google Chat

> Post every Ikiform submission to a Google Chat space as a card, through a small relay that verifies the signature and formats the message.

Published 2026-10-23 · Guide, Google Chat · https://ikiform.com/blog/form-submissions-to-google-chat

Teams on Google Workspace can get new submissions where they already talk. This guide posts each Ikiform submission to a Google Chat space as a card, with the form name in the header and one paragraph per field.

Diagram: How a submission gets from your form to Google Chat

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and sends a signed webhook to your relay.
3. The relay checks the signature, builds a card and posts it to the space's webhook.
4. Google Chat answers the relay, and the relay answers Ikiform.

Ikiform signs the delivery. The relay checks it, builds a card, and posts it to the space's webhook.

## Why there's a relay

A Google Chat webhook expects a message with `text` or `cardsV2`. Ikiform sends a submission event shaped as `{ "type": ..., "data": ... }`, which Chat can't display.

> Ikiform sends its own JSON shape to every endpoint and can't send a custom or templated body. Google Chat expects its own shape, so pasting the Google Chat URL straight into Ikiform doesn't work. A small relay in between verifies the signature and reformats the message.

The relay also keeps the space's URL private and checks Ikiform's signature, so nobody else can post to your space through it. If you'd rather not deploy code, [n8n](https://ikiform.com/blog/form-submissions-to-n8n.md), [Zapier](https://ikiform.com/blog/form-submissions-to-zapier.md) and [Make](https://ikiform.com/blog/form-submissions-to-make.md) can post to Google Chat too.

## Before you start

- An Ikiform form that already receives submissions.
- A Google Workspace Business or Enterprise account. Webhooks aren't available on personal Gmail accounts, and a Workspace admin can turn them off.
- Somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app on Vercel or any other host.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## Set it up

### Step 1: Create a Google Chat webhook

1. Open Google Chat in a browser. Webhooks can't be added from the mobile app.
2. Open the space, click the arrow next to its name, and choose **Apps & integrations**.
3. Choose **Add webhooks**. Enter a name, such as `Ikiform`, and an avatar URL if you want one, then **Save**.
4. Next to the new webhook, choose **More**, then **Copy link**.

The URL looks like `https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?key=...&token=...`. If **Add webhooks** is missing, your Workspace admin has turned webhooks off. Check it works before going further:

`Terminal`:

```bash
curl -X POST "$GOOGLE_CHAT_WEBHOOK_URL" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{"text":"Hello from the terminal"}'
```

Chat answers with the message it created, and it shows up in the space. Treat the URL as a secret: anyone who has it can post to that space.

### Step 2: Write the relay

Pick the platform you already use. Both versions verify the signature with `@ikiform/sdk`, build the card, and turn Chat errors into answers Ikiform retries.

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  GOOGLE_CHAT_WEBHOOK_URL: string;
}

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function escape(text: string) {
  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\n", "<br>");
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function bytes(text: string) {
  return new TextEncoder().encode(text).length;
}

function toChat(event: WebhookEvent) {
  if (event.type === "endpoint.test") return { text: "Ikiform test event received. Submissions will appear here." };
  const { form, fields, submission_id, truncated } = event.data;
  const widgets: { textParagraph: { text: string } }[] = [];
  let budget = 24_000;
  for (const [name, value] of Object.entries(fields)) {
    const text = `<b>${escape(clip(name, 100))}</b><br>${escape(clip(valueText(value), 2000))}`;
    if (bytes(text) > budget) break;
    budget -= bytes(text);
    widgets.push({ textParagraph: { text } });
  }
  const more = Object.keys(fields).length - widgets.length;
  if (more > 0) widgets.push({ textParagraph: { text: `${more} more fields in Ikiform.` } });
  const footer = truncated ? "Too large to show here. Open it in Ikiform." : submission_id;
  widgets.push({ textParagraph: { text: `<font color="#80868b">${footer}</font>` } });
  return {
    text: "New form submission",
    cardsV2: [
      {
        cardId: "submission",
        card: {
          header: { title: clip(form.name, 200), subtitle: "New submission" },
          sections: [{ widgets }],
        },
      },
    ],
  };
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await fetch(env.GOOGLE_CHAT_WEBHOOK_URL, {
      method: "POST",
      headers: { "content-type": "application/json; charset=UTF-8" },
      body: JSON.stringify(toChat(event)),
    });
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Google Chat rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Google Chat answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/google-chat/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

function escape(text: string) {
  return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\n", "<br>");
}

function clip(text: string, max: number) {
  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
}

function bytes(text: string) {
  return new TextEncoder().encode(text).length;
}

function toChat(event: WebhookEvent) {
  if (event.type === "endpoint.test") return { text: "Ikiform test event received. Submissions will appear here." };
  const { form, fields, submission_id, truncated } = event.data;
  const widgets: { textParagraph: { text: string } }[] = [];
  let budget = 24_000;
  for (const [name, value] of Object.entries(fields)) {
    const text = `<b>${escape(clip(name, 100))}</b><br>${escape(clip(valueText(value), 2000))}`;
    if (bytes(text) > budget) break;
    budget -= bytes(text);
    widgets.push({ textParagraph: { text } });
  }
  const more = Object.keys(fields).length - widgets.length;
  if (more > 0) widgets.push({ textParagraph: { text: `${more} more fields in Ikiform.` } });
  const footer = truncated ? "Too large to show here. Open it in Ikiform." : submission_id;
  widgets.push({ textParagraph: { text: `<font color="#80868b">${footer}</font>` } });
  return {
    text: "New form submission",
    cardsV2: [
      {
        cardId: "submission",
        card: {
          header: { title: clip(form.name, 200), subtitle: "New submission" },
          sections: [{ widgets }],
        },
      },
    ],
  };
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await fetch(process.env.GOOGLE_CHAT_WEBHOOK_URL!, {
    method: "POST",
    headers: { "content-type": "application/json; charset=UTF-8" },
    body: JSON.stringify(toChat(event)),
  });
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Google Chat rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Google Chat answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

Diagram: How the relay maps an Ikiform submission to Chat card

1. form.name: Contact becomes header title: Contact.
2. header subtitle: New submission is added by the relay.
3. fields.name: Ada becomes paragraph: name / Ada.
4. fields.email: ada@example.com becomes paragraph: email / ada@example.com.
5. fields.message: Hello becomes paragraph: message / Hello.
6. submission_id becomes grey paragraph: sub_….

Every value is escaped, so a visitor can't add tags, links or mentions.

For the sample submission above, the relay posts this to the space:

`Google Chat message`:

```json
{
  "text": "New form submission",
  "cardsV2": [
    {
      "cardId": "submission",
      "card": {
        "header": { "title": "Contact", "subtitle": "New submission" },
        "sections": [
          {
            "widgets": [
              { "textParagraph": { "text": "<b>name</b><br>Ada" } },
              { "textParagraph": { "text": "<b>email</b><br>ada@example.com" } },
              { "textParagraph": { "text": "<b>message</b><br>Hello" } },
              { "textParagraph": { "text": "<font color=\"#80868b\">sub_01k7v2c9t3e8m5q4x6z0a1b2c3</font>" } }
            ]
          }
        ]
      }
    }
  ]
}
```

- Card text paragraphs use a small set of HTML tags. The relay escapes `&`, `<` and `>` in every value, so a visitor can't add tags, links or mentions.
- A message can be 32,000 bytes. The relay cuts long values and stops adding fields at about 24 KB, then says how many it left out.
- The top-level `text` is what shows in notifications.
- A `429` becomes a `503` with Chat's `Retry-After`, or 30 seconds when there isn't one, so Ikiform waits before it tries again. Any other Chat error becomes a `502`, which Ikiform retries.

### Step 3: Deploy it

### Cloudflare Worker

`Terminal`:

```bash
mkdir ikiform-google-chat && cd ikiform-google-chat
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

Save the Worker code as `src/index.ts`, then set the route in `wrangler.jsonc`:

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-google-chat",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

Add both secrets and deploy:

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put GOOGLE_CHAT_WEBHOOK_URL
npx wrangler deploy
```

Your relay URL is `https://hooks.example.com/`.

### Next.js

Add `@ikiform/sdk` to the app, save the route handler, and set `IKIFORM_WEBHOOK_SECRET` and `GOOGLE_CHAT_WEBHOOK_URL` in your host's environment variables. On Vercel the relay URL is `https://your-app.vercel.app/api/ikiform/google-chat`. Use the production domain: Vercel's deployment protection blocks requests to protected preview URLs.

### Step 4: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste your relay URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Google Chat Leads space", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 5: Add the secret to the relay

Set `IKIFORM_WEBHOOK_SECRET` to the `whsec_` secret. On Cloudflare run `npx wrangler secret put IKIFORM_WEBHOOK_SECRET` again; it takes effect right away. On Vercel, update the variable and redeploy.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in Google Chat.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event posts a short line to the space. A real submission posts the card, with the submission id at the bottom.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What the relay tells Ikiform when Google Chat answers

1. Google Chat accepts the request: the relay answers 204, and Ikiform marks the delivery succeeded.
2. Google Chat is rate limited (429): the relay answers 503 with Retry-After (retry-after or 30 s), and Ikiform waits that long before it tries again.
3. Google Chat answers with any other error: the relay answers 502, and Ikiform retries, 8 retries over about 3 d 6 h.

Google Chat allows one request per second per space, shared by every webhook in it. A burst of submissions can hit that, and the relay tells Ikiform to wait, so the extra messages arrive a little later rather than not at all.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| `502` with `Google Chat answered 400` | Chat refused the message. The relay's logs have Chat's error; check that the URL was copied in full, with both `key` and `token`. |
| `502` with `Google Chat answered 403` or `404` | The webhook was deleted, the space is gone, or an admin turned webhooks off. Create a new webhook and update `GOOGLE_CHAT_WEBHOOK_URL`. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| The same submission arrives twice | A retry after a slow or failed answer. Every retry carries the same `webhook-id`, so skip ids you've already handled. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

To keep each form's submissions in one thread, set a `threadKey` and ask Chat to reply in that thread. Replace the `fetch` call's URL and body with these:

`Threaded replies`:

```ts
const url = new URL(env.GOOGLE_CHAT_WEBHOOK_URL);
url.searchParams.set("messageReplyOption", "REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD");
const body = { ...toChat(event), thread: { threadKey: event.type === "submission.created" ? event.data.form.id : "test" } };
```

- Send each form to its own space: add one webhook per space and one Ikiform endpoint per form. Pro allows 3 endpoints.
- Skip duplicates by storing the `webhook-id` header, as in [Receiving webhooks](https://ikiform.com/docs/guides/webhook-handlers.md#duplicates).

| Google reference | Link |
| --- | --- |
| Incoming webhooks | [developers.google.com](https://developers.google.com/workspace/chat/quickstart/webhooks) |
| Formatting messages | [developers.google.com](https://developers.google.com/workspace/chat/format-messages) |
| Message limits and threads | [developers.google.com](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/create) |

---

Source: https://ikiform.com/blog/form-submissions-to-linear-and-github-issues

# Create Linear or GitHub issues from form submissions

> Open a Linear issue or a GitHub issue for every bug report or feature request sent through an Ikiform form, with a relay that verifies the signature.

Published 2026-10-23 · Guide, Linear, GitHub · https://ikiform.com/blog/form-submissions-to-linear-and-github-issues

A bug report form is more useful when each report lands where the work happens. This guide turns each Ikiform submission into an issue, in Linear or in a GitHub repository. Pick one; the steps are the same apart from the API call.

Diagram: How a submission gets from your form to Linear or GitHub

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and sends a signed webhook to your relay.
3. The relay checks the signature, builds an issue title and body and creates the issue with the tracker's API.
4. Linear or GitHub answers the relay, and the relay answers Ikiform.

The relay checks Ikiform's signature, then creates an issue with the tracker's API.

## Why there's a relay

Linear and GitHub create issues through authenticated API calls, each with its own body. Ikiform can't add an API key or reshape its body, so a relay makes the call. Your API key stays in the relay, never in Ikiform.

## Before you start

- An Ikiform form that already receives submissions. A `subject` field makes good issue titles; without one, the relay uses `name`, then the submission id.
- For Linear, a workspace where you can create API keys. For GitHub, a repository where you can create issues.
- Somewhere to run the relay: a Cloudflare account with a domain on it, or a Next.js app on Vercel or any other host.

## What Ikiform sends

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## What the issue looks like

The title is the form name and the `subject` field, like `Bug report: Export button does nothing`. The body has one section per field. Each value sits in a code block, so a visitor can't @-mention your team, add images or break the layout:

Diagram: How the relay maps an Ikiform submission to issue

1. form.name + fields.subject becomes title: Bug report: Export button does nothing.
2. fields.name becomes body: name, value in a code block.
3. fields.email becomes body: email, value in a code block.
4. fields.message becomes body: message, value in a code block.
5. submission_id + delivery id becomes body: last line with both ids.

No subject field? The title falls back to name, then the submission id.

`Issue body`:

````text
**name**

```text
Ada
```

**email**

```text
ada@example.com
```

**message**

```text
Hello
```

Ikiform submission `sub_01k7v2c9t3e8m5q4x6z0a1b2c3`, delivery `dlv_01k7v2d4n8r2p6s0w3y5b7c9e1`
````

## Linear

### Step 1: Create an API key

In Linear, open [Settings → Security & access](https://linear.app/settings/account/security) and create a personal API key. Linear expects it in the `Authorization` header as is, without `Bearer`.

### Step 2: Find the team ID

`Terminal`:

```bash
curl https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ teams { nodes { id name } } }"}'
```

`Response`:

```json
{
  "data": {
    "teams": {
      "nodes": [{ "id": "9cfb482a-0000-0000-0000-000000000000", "name": "Support" }]
    }
  }
}
```

### Step 3: Write the relay

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  LINEAR_API_KEY: string;
  LINEAR_TEAM_ID: string;
}

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

const TITLE_FIELD = "subject";

function fence(text: string) {
  const longest = Math.max(2, ...Array.from(text.matchAll(/`+/g), (match) => match[0].length));
  const marker = "`".repeat(longest + 1);
  return `${marker}text\n${text}\n${marker}`;
}

function issueContent(event: Extract<WebhookEvent, { type: "submission.created" }>) {
  const { form, fields, submission_id, truncated } = event.data;
  const subject = fields[TITLE_FIELD] ?? fields.name ?? submission_id;
  const title = `${form.name}: ${valueText(subject)}`.replace(/\s+/g, " ").slice(0, 200);
  const sections: string[] = [];
  let length = 0;
  for (const [name, value] of Object.entries(fields)) {
    const section = `**${name.replace(/[^\w .-]/g, "")}**\n\n${fence(valueText(value))}`;
    length += section.length + 2;
    if (length > 60000) {
      sections.push("More fields didn't fit. Open the submission in Ikiform.");
      break;
    }
    sections.push(section);
  }
  if (truncated) sections.push("The submission was too large to include. Open it in Ikiform.");
  sections.push(`Ikiform submission \`${submission_id}\`, delivery \`${event.id}\``);
  return { title, body: sections.join("\n\n") };
}

const ISSUE_CREATE = `mutation IssueCreate($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue { identifier url }
  }
}`;

interface LinearResult {
  data?: { issueCreate?: { success: boolean } };
  errors?: { message: string; extensions?: { code?: string } }[];
}

async function createIssue(event: WebhookEvent, apiKey: string, teamId: string) {
  if (event.type !== "submission.created") return new Response(null, { status: 204 });
  const { title, body } = issueContent(event);
  const response = await fetch("https://api.linear.app/graphql", {
    method: "POST",
    headers: { authorization: apiKey, "content-type": "application/json" },
    body: JSON.stringify({ query: ISSUE_CREATE, variables: { input: { teamId, title, description: body } } }),
  });
  const result = (await response.json().catch(() => null)) as LinearResult | null;
  if (result?.errors?.some((error) => error.extensions?.code === "RATELIMITED")) {
    return new Response(null, { status: 429, headers: { "retry-after": "60" } });
  }
  if (!response.ok) return new Response(null, { status: response.status, headers: response.headers });
  if (!result?.data?.issueCreate?.success) return new Response(null, { status: 500 });
  return new Response(null, { status: 201 });
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await createIssue(event, env.LINEAR_API_KEY, env.LINEAR_TEAM_ID);
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("Linear rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`Linear answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/linear/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

const TITLE_FIELD = "subject";

function fence(text: string) {
  const longest = Math.max(2, ...Array.from(text.matchAll(/`+/g), (match) => match[0].length));
  const marker = "`".repeat(longest + 1);
  return `${marker}text\n${text}\n${marker}`;
}

function issueContent(event: Extract<WebhookEvent, { type: "submission.created" }>) {
  const { form, fields, submission_id, truncated } = event.data;
  const subject = fields[TITLE_FIELD] ?? fields.name ?? submission_id;
  const title = `${form.name}: ${valueText(subject)}`.replace(/\s+/g, " ").slice(0, 200);
  const sections: string[] = [];
  let length = 0;
  for (const [name, value] of Object.entries(fields)) {
    const section = `**${name.replace(/[^\w .-]/g, "")}**\n\n${fence(valueText(value))}`;
    length += section.length + 2;
    if (length > 60000) {
      sections.push("More fields didn't fit. Open the submission in Ikiform.");
      break;
    }
    sections.push(section);
  }
  if (truncated) sections.push("The submission was too large to include. Open it in Ikiform.");
  sections.push(`Ikiform submission \`${submission_id}\`, delivery \`${event.id}\``);
  return { title, body: sections.join("\n\n") };
}

const ISSUE_CREATE = `mutation IssueCreate($input: IssueCreateInput!) {
  issueCreate(input: $input) {
    success
    issue { identifier url }
  }
}`;

interface LinearResult {
  data?: { issueCreate?: { success: boolean } };
  errors?: { message: string; extensions?: { code?: string } }[];
}

async function createIssue(event: WebhookEvent, apiKey: string, teamId: string) {
  if (event.type !== "submission.created") return new Response(null, { status: 204 });
  const { title, body } = issueContent(event);
  const response = await fetch("https://api.linear.app/graphql", {
    method: "POST",
    headers: { authorization: apiKey, "content-type": "application/json" },
    body: JSON.stringify({ query: ISSUE_CREATE, variables: { input: { teamId, title, description: body } } }),
  });
  const result = (await response.json().catch(() => null)) as LinearResult | null;
  if (result?.errors?.some((error) => error.extensions?.code === "RATELIMITED")) {
    return new Response(null, { status: 429, headers: { "retry-after": "60" } });
  }
  if (!response.ok) return new Response(null, { status: response.status, headers: response.headers });
  if (!result?.data?.issueCreate?.success) return new Response(null, { status: 500 });
  return new Response(null, { status: 201 });
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await createIssue(event, process.env.LINEAR_API_KEY!, process.env.LINEAR_TEAM_ID!);
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("Linear rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`Linear answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

- Linear reports rate limits as HTTP `400` with `RATELIMITED` in `errors[].extensions.code`, not as `429`. The relay turns that into a `503` with `Retry-After: 60`, so Ikiform waits and tries again.
- GraphQL can answer `200` with errors. The relay only answers `2xx` when `issueCreate.success` is `true`.
- `endpoint.test` events return `204` and create nothing.

### Step 4: Deploy it

`Terminal`:

```bash
mkdir ikiform-issues && cd ikiform-issues
npm init -y
npm install @ikiform/sdk
npm install -D wrangler
```

Save the Worker code as `src/index.ts`, then set the route in `wrangler.jsonc`:

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-issues",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }]
}
```

> Ikiform refuses `workers.dev` URLs, so the Worker needs a hostname on a domain you have on Cloudflare, like `hooks.example.com`. The `custom_domain` route creates the DNS record and certificate for you on deploy.

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put LINEAR_API_KEY
npx wrangler secret put LINEAR_TEAM_ID
npx wrangler deploy
```

On Next.js, add `@ikiform/sdk`, save the route handler, and set `IKIFORM_WEBHOOK_SECRET`, `LINEAR_API_KEY` and `LINEAR_TEAM_ID` in your host's environment variables.

## GitHub Issues

### Step 1: Create a fine-grained token

1. In GitHub, open **Settings → Developer settings → Personal access tokens → Fine-grained tokens** and generate a new token.
2. Under repository access, pick only the repository that should get the issues.
3. Under repository permissions, set **Issues** to **Read and write**.

Set `GITHUB_REPO` to `owner/repo`, for example `acme/website`.

### Step 2: Write the relay

**Cloudflare Worker** (`src/index.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  GITHUB_TOKEN: string;
  GITHUB_REPO: string;
}

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

const TITLE_FIELD = "subject";

function fence(text: string) {
  const longest = Math.max(2, ...Array.from(text.matchAll(/`+/g), (match) => match[0].length));
  const marker = "`".repeat(longest + 1);
  return `${marker}text\n${text}\n${marker}`;
}

function issueContent(event: Extract<WebhookEvent, { type: "submission.created" }>) {
  const { form, fields, submission_id, truncated } = event.data;
  const subject = fields[TITLE_FIELD] ?? fields.name ?? submission_id;
  const title = `${form.name}: ${valueText(subject)}`.replace(/\s+/g, " ").slice(0, 200);
  const sections: string[] = [];
  let length = 0;
  for (const [name, value] of Object.entries(fields)) {
    const section = `**${name.replace(/[^\w .-]/g, "")}**\n\n${fence(valueText(value))}`;
    length += section.length + 2;
    if (length > 60000) {
      sections.push("More fields didn't fit. Open the submission in Ikiform.");
      break;
    }
    sections.push(section);
  }
  if (truncated) sections.push("The submission was too large to include. Open it in Ikiform.");
  sections.push(`Ikiform submission \`${submission_id}\`, delivery \`${event.id}\``);
  return { title, body: sections.join("\n\n") };
}

async function createIssue(event: WebhookEvent, token: string, repo: string) {
  if (event.type !== "submission.created") return new Response(null, { status: 204 });
  const { title, body } = issueContent(event);
  return fetch(`https://api.github.com/repos/${repo}/issues`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${token}`,
      accept: "application/vnd.github+json",
      "content-type": "application/json",
      "user-agent": "ikiform-issues-relay",
      "x-github-api-version": "2026-03-10",
    },
    body: JSON.stringify({ title, body }),
  });
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    let event: WebhookEvent;
    try {
      event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
    const response = await createIssue(event, env.GITHUB_TOKEN, env.GITHUB_REPO);
    if (response.status === 429) {
      const retryAfter = response.headers.get("retry-after") ?? "30";
      return new Response("GitHub rate limit", { status: 503, headers: { "retry-after": retryAfter } });
    }
    if (!response.ok) return new Response(`GitHub answered ${response.status}`, { status: 502 });
    return new Response(null, { status: 204 });
  },
};
```

**Next.js** (`app/api/ikiform/github/route.ts`)

```ts
import { verifyWebhook, type WebhookEvent, WebhookVerificationError } from "@ikiform/sdk/webhooks";

function valueText(value: unknown): string {
  if (value === null || value === undefined || value === "") return "(empty)";
  if (Array.isArray(value)) return value.map(valueText).join(", ");
  if (typeof value === "object") return JSON.stringify(value);
  return String(value);
}

const TITLE_FIELD = "subject";

function fence(text: string) {
  const longest = Math.max(2, ...Array.from(text.matchAll(/`+/g), (match) => match[0].length));
  const marker = "`".repeat(longest + 1);
  return `${marker}text\n${text}\n${marker}`;
}

function issueContent(event: Extract<WebhookEvent, { type: "submission.created" }>) {
  const { form, fields, submission_id, truncated } = event.data;
  const subject = fields[TITLE_FIELD] ?? fields.name ?? submission_id;
  const title = `${form.name}: ${valueText(subject)}`.replace(/\s+/g, " ").slice(0, 200);
  const sections: string[] = [];
  let length = 0;
  for (const [name, value] of Object.entries(fields)) {
    const section = `**${name.replace(/[^\w .-]/g, "")}**\n\n${fence(valueText(value))}`;
    length += section.length + 2;
    if (length > 60000) {
      sections.push("More fields didn't fit. Open the submission in Ikiform.");
      break;
    }
    sections.push(section);
  }
  if (truncated) sections.push("The submission was too large to include. Open it in Ikiform.");
  sections.push(`Ikiform submission \`${submission_id}\`, delivery \`${event.id}\``);
  return { title, body: sections.join("\n\n") };
}

async function createIssue(event: WebhookEvent, token: string, repo: string) {
  if (event.type !== "submission.created") return new Response(null, { status: 204 });
  const { title, body } = issueContent(event);
  return fetch(`https://api.github.com/repos/${repo}/issues`, {
    method: "POST",
    headers: {
      authorization: `Bearer ${token}`,
      accept: "application/vnd.github+json",
      "content-type": "application/json",
      "user-agent": "ikiform-issues-relay",
      "x-github-api-version": "2026-03-10",
    },
    body: JSON.stringify({ title, body }),
  });
}

export async function POST(request: Request) {
  const payload = await request.text();
  let event: WebhookEvent;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  const response = await createIssue(event, process.env.GITHUB_TOKEN!, process.env.GITHUB_REPO!);
  if (response.status === 429) {
    const retryAfter = response.headers.get("retry-after") ?? "30";
    return new Response("GitHub rate limit", { status: 503, headers: { "retry-after": retryAfter } });
  }
  if (!response.ok) return new Response(`GitHub answered ${response.status}`, { status: 502 });
  return new Response(null, { status: 204 });
}
```

- GitHub rejects requests without a `User-Agent` header, so the relay always sends one.
- A new issue answers `201`. A `410` means issues are turned off for the repository, and a `422` means GitHub refused the content.
- Labels and assignees need push access, and GitHub drops them silently without it. That's why this relay sends only a title and a body. Add `labels` once the token's account can push.

### Step 3: Deploy it

Use the same project setup as for Linear, with GitHub's secrets:

`Terminal`:

```bash
npx wrangler secret put IKIFORM_WEBHOOK_SECRET
npx wrangler secret put GITHUB_TOKEN
npx wrangler secret put GITHUB_REPO
npx wrangler deploy
```

On Next.js, set `IKIFORM_WEBHOOK_SECRET`, `GITHUB_TOKEN` and `GITHUB_REPO` in your host's environment variables.

## Connect Ikiform

### Step 1: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste your relay URL into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Bug reports to Linear", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 2: Add the secret to the relay

Set `IKIFORM_WEBHOOK_SECRET` to the `whsec_` secret. On Cloudflare run `npx wrangler secret put IKIFORM_WEBHOOK_SECRET` again. On other hosts, update the variable and redeploy.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in Linear or GitHub as a new issue.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

The test event returns `204` from the relay and creates nothing.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What the relay tells Ikiform when Linear answers

1. Linear accepts the request: the relay answers 204, and Ikiform marks the delivery succeeded.
2. Linear is rate limited (400): the relay answers 503 with Retry-After (retry-after: 60), and Ikiform waits that long before it tries again.
3. Linear answers with any other error: the relay answers 502, and Ikiform retries, 8 retries over about 3 d 6 h.

Linear reports a rate limit as a 400 with RATELIMITED in the errors. The relay answers 503 with Retry-After: 60. For GitHub, a 429 becomes a 503 and any other error a 502, the same way.

### Duplicate issues

Ikiform retries when the relay doesn't answer `2xx` in time. If the tracker created the issue but answered slowly, the retry creates a second one. It's rare, and every issue ends with the delivery id, so duplicates are easy to spot and close.

> For strict once-only, store each `webhook-id` before calling the API, for example in Workers KV, and answer `204` straight away when you've seen it. [Receiving webhooks](https://ikiform.com/docs/guides/webhook-handlers.md#duplicates) shows the pattern.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| `502` with `Linear answered 400` | The API key or team ID is wrong. Personal keys go in `Authorization` without `Bearer`. Run the teams query above with the same key. |
| `502` with `Linear answered 500` | Linear answered but `issueCreate.success` wasn't `true`. Log `result.errors` in the relay to see why. |
| `502` with `GitHub answered 403` or `404` | The token can't write issues on this repository, or `GITHUB_REPO` is misspelled. Fine-grained tokens only see the repositories you picked. |
| `502` with `GitHub answered 410` | Issues are turned off in the repository's settings. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

- Add a label or a priority: Linear's `issueCreate` takes `labelIds` and `priority`, and GitHub takes `labels`.
- Send bug reports and feature requests to different teams with one endpoint per form.
- Tell the team in chat as well: see [Send form submissions to Slack](https://ikiform.com/blog/form-submissions-to-slack.md).

| Reference | Link |
| --- | --- |
| Linear GraphQL API | [linear.app/developers](https://linear.app/developers/graphql) |
| Linear rate limits | [linear.app/developers](https://linear.app/developers/rate-limiting) |
| GitHub: create an issue | [docs.github.com](https://docs.github.com/en/rest/issues/issues#create-an-issue) |
| GitHub: token permissions | [docs.github.com](https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens) |
| GitHub: API versions | [docs.github.com](https://docs.github.com/en/rest/about-the-rest-api/api-versions) |

---

Source: https://ikiform.com/blog/form-submissions-to-your-own-server

# Receive form submissions on your own server

> Verified Ikiform webhook handlers for a Next.js route handler, Express, a Cloudflare Worker, FastAPI and Flask, plus raw body pitfalls, duplicates and local testing.

Published 2026-10-23 · Guide, Webhooks · https://ikiform.com/blog/form-submissions-to-your-own-server

Sometimes the right destination is your own code: a database, a CRM sync, a welcome email. This guide shows complete handlers for the common stacks. Each one reads the raw body, checks Ikiform's signature, skips repeats and answers fast.

Diagram: How a submission gets from your form to your server

1. A visitor submits your form, and it posts to Ikiform.
2. Ikiform stores the submission and posts it to your endpoint, signed with your endpoint's secret.
3. Your handler verifies the signature against the raw body, skips delivery ids it has seen, and answers 2xx within 15 seconds.
4. Slow work, like notifications, runs after the answer.

Ikiform posts each submission to your endpoint, signed with your endpoint's secret.

## Before you start

- An Ikiform form that already receives submissions.
- A server reachable on a public `https://` URL. For local work, see [Testing locally](#local).
- `@ikiform/sdk` for the TypeScript and JavaScript handlers. It uses Web Crypto only, so it runs in Node 20 and later, Workers, Deno and Bun.

## What Ikiform sends

`Headers`:

```http
POST /ikiform HTTP/1.1
content-type: application/json
user-agent: Ikiform-Webhooks/1.0
webhook-id: dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792756800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
```

Every delivery is a `POST` with a JSON body. The body has the same shape for every endpoint, and you can't change it. A submission looks like this:

`submission.created`:

```json
{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-23T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-23T12:00:00.000Z",
    "truncated": false
  }
}
```

The form's values are in `data.fields`, keyed by the input `name`. A test from the dashboard sends an `endpoint.test` event instead, with `data.endpoint_id` and `data.message` and no fields. The full reference is on [Webhooks](https://ikiform.com/docs/webhooks.md#payloads).

## The four rules

| Rule | Why |
| --- | --- |
| Verify against the raw body | The signature covers the exact bytes. Parsed and re-serialized JSON can differ by a space and fail |
| Reject old timestamps | A signature older than 5 minutes may be a replay. The SDK does this for you |
| Skip repeats | Retries carry the same `webhook-id`. Store it with a unique constraint |
| Answer within 15 seconds | Slower answers count as failures and are retried. Do slow work after answering |

## Handlers

### Next.js route handler

**Route handler** (`app/api/webhooks/ikiform/route.ts`)

```ts
import { after } from "next/server";
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";
import { notifyTeam, saveLead } from "@/lib/leads";

export async function POST(request: Request) {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET!,
    });
    if (event.type === "submission.created") {
      const created = await saveLead(event.id, event.data.fields);
      if (created) after(() => notifyTeam(event.data.form.name, event.data.fields));
    }
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response(error.reason, { status: 400 });
    }
    throw error;
  }
}
```

**lib/leads.ts**

```ts
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function saveLead(deliveryId: string, fields: Record<string, unknown>) {
  const result = await pool.query(
    "insert into leads (delivery_id, fields) values ($1, $2) on conflict (delivery_id) do nothing",
    [deliveryId, JSON.stringify(fields)],
  );
  return result.rowCount === 1;
}

export async function notifyTeam(form: string, fields: Record<string, unknown>) {
  console.info(`New ${form} submission`, fields);
}
```

**SQL** (`schema.sql`)

```text
create table leads (
  id bigint generated always as identity primary key,
  delivery_id text not null unique,
  fields jsonb not null,
  received_at timestamptz not null default now()
);
```

`request.text()` gives the raw body. The insert uses `on conflict do nothing`, so a retry of a delivery you already stored returns `false` and skips the notification. `after()` runs the notification once the response is sent, so Ikiform gets its `204` right away.

### Express

`server.js`:

```js
import express from "express";
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

const app = express();

app.post("/webhooks/ikiform", express.text({ type: "application/json", limit: "512kb" }), async (req, res) => {
  try {
    const event = await verifyWebhook({
      payload: req.body,
      headers: req.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET,
    });
    if (event.type === "submission.created") {
      console.info("New submission", event.id, event.data.fields);
    }
    res.status(204).end();
  } catch (error) {
    if (error instanceof WebhookVerificationError) return res.status(400).send(error.reason);
    res.status(500).end();
  }
});

app.use(express.json());

app.listen(3000);
```

`express.text({ type: "application/json" })` keeps the body as the exact string Ikiform sent. A global `express.json()` registered before this route parses the body first and the signature fails, so register the webhook route first, as here.

### Cloudflare Worker

`src/index.ts`:

```ts
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

interface Env {
  IKIFORM_WEBHOOK_SECRET: string;
  LEADS: KVNamespace;
}

export default {
  async fetch(request: Request, env: Env) {
    if (request.method !== "POST") return new Response(null, { status: 405 });
    const payload = await request.text();
    try {
      const event = await verifyWebhook({ payload, headers: request.headers, secret: env.IKIFORM_WEBHOOK_SECRET });
      if (event.type === "submission.created") {
        await env.LEADS.put(event.id, JSON.stringify(event.data));
      }
      return new Response(null, { status: 204 });
    } catch (error) {
      if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
      throw error;
    }
  },
};
```

`wrangler.jsonc`:

```json
{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "ikiform-webhooks",
  "main": "src/index.ts",
  "compatibility_date": "2026-10-01",
  "routes": [{ "pattern": "hooks.example.com", "custom_domain": true }],
  "kv_namespaces": [{ "binding": "LEADS", "id": "<your KV namespace id>" }]
}
```

Storing each submission under its delivery id makes retries harmless: writing the same key twice leaves one entry. Run `npx wrangler types` for the `KVNamespace` type. Ikiform refuses `workers.dev` URLs, so the `custom_domain` route puts the Worker on a hostname of yours.

### Python: FastAPI and Flask

**FastAPI** (`main.py`)

```python
import base64
import hashlib
import hmac
import json
import os
import time

from fastapi import BackgroundTasks, FastAPI, Request, Response

app = FastAPI()
SECRET = base64.b64decode(os.environ["IKIFORM_WEBHOOK_SECRET"].removeprefix("whsec_"))


def verify(body: bytes, headers) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signatures or not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    content = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(SECRET, content, hashlib.sha256).digest()).decode()
    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return True
    return False


def save_lead(delivery_id: str, fields: dict) -> None:
    print("New submission", delivery_id, fields)


@app.post("/webhooks/ikiform")
async def ikiform_webhook(request: Request, background: BackgroundTasks):
    body = await request.body()
    if not verify(body, request.headers):
        return Response("invalid signature", status_code=400)
    event = json.loads(body)
    if event["type"] == "submission.created":
        background.add_task(save_lead, event["id"], event["data"]["fields"])
    return Response(status_code=204)
```

**Flask** (`app.py`)

```python
import base64
import hashlib
import hmac
import os
import time

from flask import Flask, request

app = Flask(__name__)
SECRET = base64.b64decode(os.environ["IKIFORM_WEBHOOK_SECRET"].removeprefix("whsec_"))


def verify(body: bytes, headers) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not msg_id or not timestamp or not signatures or not timestamp.isdigit():
        return False
    if abs(time.time() - int(timestamp)) > 300:
        return False
    content = f"{msg_id}.{timestamp}.".encode() + body
    expected = base64.b64encode(hmac.new(SECRET, content, hashlib.sha256).digest()).decode()
    for entry in signatures.split(" "):
        version, _, signature = entry.partition(",")
        if version == "v1" and hmac.compare_digest(signature, expected):
            return True
    return False


def save_lead(delivery_id: str, fields: dict) -> None:
    print("New submission", delivery_id, fields)


@app.post("/webhooks/ikiform")
def ikiform_webhook():
    body = request.get_data()
    if not verify(body, request.headers):
        return "invalid signature", 400
    event = request.get_json()
    if event["type"] == "submission.created":
        save_lead(event["id"], event["data"]["fields"])
    return "", 204
```

Read the bytes with `await request.body()` in FastAPI or `request.get_data()` in Flask, before anything parses them. In FastAPI, don't declare a Pydantic model as the body parameter; that parses the JSON before you can check it. `BackgroundTasks` runs `save_lead` after the `204` is sent.

### Without the SDK

Ikiform uses the [Standard Webhooks](https://www.standardwebhooks.com) scheme, so any Standard Webhooks library works. By hand, in Node:

`verify.js`:

```js
import { createHmac, timingSafeEqual } from "node:crypto";

const secret = Buffer.from(process.env.IKIFORM_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");

export function verify(body, headers) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${id}.${timestamp}.${body}`).digest();
  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}
```

Diagram: How your handler checks an Ikiform signature

1. Read webhook-id, webhook-timestamp and the raw body exactly as received.
2. Reject the request if the timestamp is more than 5 minutes from now.
3. Base64-decode the part of the secret after whsec_ and use it as the HMAC key.
4. Compute HMAC-SHA256 of id.timestamp.body and base64-encode it.
5. Compare it, in constant time, with each v1 value in webhook-signature. There are two while a secret rotates.
6. If one matches: 2xx, handle it, answer fast.
7. If none match: 400, with the reason.

The signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`. The key is the base64-decoded part of the secret after `whsec_`. The header can hold several space-separated `v1,` signatures while a secret rotates; accept the request if any one matches.

## Getting the raw body

| Framework | Raw body | Pitfall |
| --- | --- | --- |
| Next.js App Router | `await request.text()` | Calling `request.json()` first |
| Next.js Pages Router | Read the stream yourself | The default body parser. Turn it off with `export const config = { api: { bodyParser: false } }` |
| Express | `express.text({ type: "application/json" })` on the route | A global `express.json()` before it |
| Hono, Workers, Deno, Bun | `await request.text()` | None |
| Fastify | A content type parser with `parseAs: "string"` | The default JSON parser |
| FastAPI | `await request.body()` | A Pydantic model as the body parameter |
| Flask | `request.get_data()` | Re-serializing `request.get_json()` |
| Django | `request.body` | CSRF middleware. Mark the view `@csrf_exempt`; the signature replaces it |

## Connect Ikiform

### Step 1: Add the endpoint in Ikiform

- In the Ikiform dashboard, open **Webhooks** and choose **Add endpoint**.
- Paste your handler's URL, like `https://example.com/webhooks/ikiform` into **URL**.
- Under **Forms**, pick one form, or **All forms** in the workspace.
- Add a **Description** if you like, such as "Production API", then choose **Add endpoint**.
- Copy the signing secret. It starts with `whsec_` and is shown in full only once.

There's no event picker. An endpoint gets `submission.created` for every accepted submission on the forms you chose, and `endpoint.test` when you send a test. A workspace on Pro can have up to 3 endpoints.

### Step 2: Set the secret

Store the `whsec_` secret as `IKIFORM_WEBHOOK_SECRET` in your server's environment, never in the code. Deploy, then send a test.

Ikiform only delivers to public `https://` URLs on port 443. IP addresses, `localhost`, internal hostnames, `workers.dev` and `pages.dev` are refused when you save the endpoint.

## Testing locally

Ikiform can't reach `localhost`. Run a tunnel that gives your local server a public `https://` URL on port 443, and add that URL as a second endpoint while you work:

`Terminal`:

```bash
cloudflared tunnel --url http://localhost:3000
ngrok http 3000
```

Cloudflare's quick tunnel prints a `trycloudflare.com` URL, and ngrok prints its own. Both change on each run unless you set up a named tunnel or a reserved domain, so **Edit** the endpoint when they do. Delete the test endpoint when you're done; Pro allows 3.

> To check a secret, headers and body without a server, paste a delivery into the [signature verifier](https://ikiform.com/docs/webhooks.md#verifier). It runs in the browser and can also generate a correctly signed example.

## Test it

Open the endpoint in Ikiform and choose **Send test**. Ikiform sends one `endpoint.test` event with no retries, and the result shows up in the endpoint's delivery log within a few seconds. Then send a real submission from your form, or from a terminal:

`Terminal`:

```bash
curl https://ikiform.com/f/frm_xxxxxxxxxxxxxxxx \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada","email":"ada@example.com","message":"Hello from curl"}'
```

A `201` with `"ok": true` means Ikiform stored it. The delivery appears on the endpoint page, and the message lands in your server's logs.

> If the form has a human check or allowed domains turned on, a post from curl is refused or marked as spam, and spam never sends a webhook. Test from your real site instead.

## How delivery works

| The receiver answers | Ikiform |
| --- | --- |
| Any `2xx` within 15 seconds | Marks the delivery succeeded |
| A redirect | Doesn't follow it, and counts a failure |
| `429` or `503` with `Retry-After` | Waits that long, up to the next step of the schedule |
| `410 Gone` | Fails the delivery and disables the endpoint |
| Anything else, or no answer in 15 seconds | Retries |

Failed deliveries are retried 8 times over about 3 d 6 h, with the same `webhook-id` each time. If every delivery to an endpoint fails for 5 days, Ikiform disables it and emails the workspace owners.

Diagram: What Ikiform does with each answer from your server

1. Any 2xx within 15 seconds: the delivery succeeded.
2. 429 or 503 with Retry-After: Ikiform waits that long, up to the next step of the retry schedule.
3. 410 Gone: the delivery fails and the endpoint is disabled.
4. A redirect, any other status, or no answer within 15 seconds: Ikiform retries, 8 retries over about 3 d 6 h, with the same webhook-id.

Answer `410 Gone` only when you want Ikiform to stop sending to this URL for good; it disables the endpoint immediately. For a short outage, answer `503` with `Retry-After`.

## Troubleshooting

| Problem | What to do |
| --- | --- |
| `400 no_matching_signature` | The secret is wrong, or the body was parsed and re-serialized before verifying. Use the `whsec_` secret of this endpoint and the raw body exactly as received. After **Roll secret**, update it within 24 hours. |
| `400 timestamp_too_old` | The signature is more than 5 minutes old. Check the server clock, and don't replay old deliveries by hand; use **Retry now** on the delivery instead, which signs it again. |
| `400 missing_headers` | A proxy or framework dropped the `webhook-*` headers, or the request didn't come from Ikiform. Header names are lowercase; look them up case-insensitively. |
| Delivery log shows `redirect_not_followed` | The URL answers with a `3xx`. Use the final URL, with the exact path and trailing slash, so it answers `2xx` directly. |
| Delivery log shows `timeout` | Nothing answered within 15 seconds. Answer first and do slow work after, or make sure the tool responds right away. |
| The same submission arrives twice | A retry after a slow or failed answer. Every retry carries the same `webhook-id`, so skip ids you've already handled. |
| Endpoint is disabled | Every delivery failed for 5 days, the URL answered `410`, or its hostname started resolving to a private address. Fix the cause, then turn **Enabled** back on and **Retry now** the failed deliveries. |
| No delivery at all | Check that the endpoint covers this form, that it's enabled, and that the submission wasn't marked as spam or held because the workspace is over its monthly limit. |

## Next steps

- Fetch more about a submission with the [REST API](https://ikiform.com/docs/api.md#get-submission), using `data.submission_id`.
- Validate fields at Ikiform's edge before they reach you: [define fields](https://ikiform.com/docs/fields.md).
- Read every header, retry and limit in [Webhooks](https://ikiform.com/docs/webhooks.md).