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.
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. Open the Share workspace, the Accept responses card, the Webhook section.
- 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. Save.
- 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.
{
"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
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| Header | Purpose |
|---|---|
| X-Kakak-Event | The event type. Currently always form.response. |
| X-Kakak-Delivery | The delivery id. Identical across all retries, so use it to reject duplicates. |
| X-Kakak-Attempt | Which attempt this is (1 to 4). |
| X-Kakak-Signature | t=<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. Take the
X-Kakak-Signatureheader and split out thetandv1values. - 2. Reject if
tis more than 5 minutes away from the server clock. - 3. Compute the HMAC-SHA256 of
t + "." + raw bodywith the secret. - 4. Compare it with
v1using a constant-time comparison. Reject if they differ. - 5. Only then parse the body as JSON.
// 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
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
// 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.
