Send 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.

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.

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, Zapier and Make 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:

{
  "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.

Set it up

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:

   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.

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 WorkerNext.js

   src/index.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 });
     },
   };

   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_….

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

   {
     "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.

3. Deploy it

   Cloudflare Worker

   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:

   {
     "$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:

   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.

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.

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:

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.

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

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.

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

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:

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.