Skip to content

Signed webhook

Send every response to your own system as JSON. Payload, headers, how to verify the X-Kakak-Signature signature, and the retry rules.

On this page

A webhook sends every new response to an address you own, for example your campus academic system, Google Apps Script, or an automation tool. Each delivery is a POST request containing JSON, signed so the receiver can confirm it really came from kakak.ai form.

Setting up a webhook

  1. 1. Open the Share workspace, the Accept responses card, the Webhook section.
  2. 2. Paste the receiving address. Use a public https address; an http address is accepted but shows a warning because it is not encrypted, and internal network addresses are rejected.
  3. 3. Save.
  4. 4. Click Show to reveal the secret (it starts with whsec_), then copy it and store it on the receiving server as an environment variable.

Payload

answers contains all answers, including link data (marked with a hidden: prefix on its name). answers_by_alias only exists when the form has questions with a short name that were answered; its keys are the short names, which makes it the easiest to use.

Example request body
{
  "event": "form.response",
  "form_id": "8f3c2a10-....",
  "response_id": "b71e9d42-....",
  "created_at": "2026-11-13T02:15:09.412Z",
  "answers": [
    { "question_id": "2d1f....", "type": "short_text", "value": "Rina Kartika" },
    { "question_id": "9a7c....", "type": "number", "value": 3.75 },
    { "question_id": "hidden:kelas", "value": "TI-2A" }
  ],
  "answers_by_alias": {
    "nama_lengkap": "Rina Kartika",
    "ipk": 3.75
  }
}

Value shapes follow the question type: numbers are stored as plain numbers, dates in ISO format, phone numbers in international format, and checkboxes as a list.

Headers sent
Content-Type: application/json
User-Agent: kakakForm-Webhook/1
X-Kakak-Event: form.response
X-Kakak-Delivery: 5b0e7c1e-2f3a-4c55-9d0a-1c2b3d4e5f60
X-Kakak-Attempt: 1
X-Kakak-Signature: t=1763000109,v1=4f9a...e21c
HeaderPurpose
X-Kakak-EventThe event type. Currently always form.response.
X-Kakak-DeliveryThe delivery id. Identical across all retries, so use it to reject duplicates.
X-Kakak-AttemptWhich attempt this is (1 to 4).
X-Kakak-Signaturet=<unix seconds>,v1=<signature>.

Verifying the signature

The v1 signature is an HMAC-SHA256 in hexadecimal, keyed with the secret whsec_... (the whole string), over the text <t>.<raw body>. Steps on the receiving server:

  1. 1. Take the X-Kakak-Signature header and split out the t and v1 values.
  2. 2. Reject if t is more than 5 minutes away from the server clock.
  3. 3. Compute the HMAC-SHA256 of t + "." + raw body with the secret.
  4. 4. Compare it with v1 using a constant-time comparison. Reject if they differ.
  5. 5. Only then parse the body as JSON.
Node.js (Express)
// Node.js + Express. Read the RAW body: the signature is computed from the exact text that was sent.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.KAKAKFORM_WEBHOOK_SECRET; // whsec_... from the Share workspace
const app = express();

app.post("/kakakform", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-Kakak-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const t = Number(parts.t);
  const body = req.body.toString("utf8");

  // Reject deliveries older than 5 minutes (prevents replay by third parties).
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400);

  const expected = createHmac("sha256", SECRET).update(t + "." + body).digest("hex");
  const given = String(parts.v1 || "");
  const ok = given.length === expected.length &&
    timingSafeEqual(Buffer.from(given), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);

  const data = JSON.parse(body);
  // Use X-Kakak-Delivery to reject duplicates when a delivery is retried.
  console.log(req.get("X-Kakak-Delivery"), data.answers_by_alias);
  res.sendStatus(200); // reply quickly; do heavy processing in your own queue
});

app.listen(3000);
Python (Flask)
# Python + Flask
import hashlib, hmac, os, time
from flask import Flask, request, abort

SECRET = os.environ["KAKAKFORM_WEBHOOK_SECRET"].encode()
app = Flask(__name__)

@app.post("/kakakform")
def kakakform():
    header = request.headers.get("X-Kakak-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    body = request.get_data()  # raw body, bytes
    t = int(parts.get("t", "0"))
    if abs(time.time() - t) > 300:
        abort(400)
    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        abort(401)
    data = request.get_json()
    print(data["answers_by_alias"] if "answers_by_alias" in data else data["answers"])
    return "", 200
PHP
<?php
// Plain PHP
$secret = getenv('KAKAKFORM_WEBHOOK_SECRET');
$body = file_get_contents('php://input'); // raw body
$header = $_SERVER['HTTP_X_KAKAK_SIGNATURE'] ?? '';
$parts = [];
foreach (explode(',', $header) as $p) {
  [$k, $v] = array_pad(explode('=', $p, 2), 2, '');
  $parts[$k] = $v;
}
$t = (int)($parts['t'] ?? 0);
if (abs(time() - $t) > 300) { http_response_code(400); exit; }
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
if (!hash_equals($expected, $parts['v1'] ?? '')) { http_response_code(401); exit; }
$data = json_decode($body, true);
http_response_code(200);

Retries and timeouts

  • The receiver has 5 seconds per attempt. Reply with a 2xx status as soon as possible, then process the data in the background.
  • If delivery fails because of a network error, a timeout, status 408, 425, 429, or 5xx, it is retried three times with delays of about 1, 3, and 9 seconds.
  • Any other 4xx status is treated as a rejection and is not retried.
  • Redirects (3xx) are not followed, but count as delivered. This keeps a Google Apps Script that answers with 302 working.
  • Deliveries run in the background, so respondents never wait for the webhook to finish.

Example

Registrations straight into the academic system

A faculty IT team connects the webhook of a lab assistant application form to an internal PHP service. The service verifies the signature, rejects delivery ids it has already processed, and then saves answers_by_alias.nim and answers_by_alias.ipk (student ID number and GPA) into its candidate assistants table.

Something unclear? Ask through the help button in the bottom right corner.