Webhook bertanda tangan
Kirim setiap jawaban ke sistemmu sendiri dalam JSON. Isi kiriman, header, cara memeriksa tanda tangan X-Kakak-Signature, dan aturan coba ulang.
Webhook mengirim setiap jawaban baru ke alamat milikmu sendiri, misalnya sistem akademik kampus, Google Apps Script, atau alat otomasi. Kiriman berupa permintaan POST berisi JSON, ditandatangani supaya penerima bisa memastikan kiriman benar dari kakak.ai form.
Memasang webhook
- 1. Buka ruang kerja Bagikan, kartu Terima jawaban, bagian Webhook.
- 2. Tempel alamat penerima. Gunakan alamat https publik; alamat http diterima tetapi diberi peringatan karena tidak terenkripsi, dan alamat jaringan internal ditolak.
- 3. Simpan.
- 4. Klik Lihat untuk menampilkan rahasia (diawali
whsec_), lalu salin dan simpan di server penerima sebagai variabel lingkungan.
Isi kiriman
answers berisi semua jawaban, termasuk data dari tautan (ditandai hidden: di depan namanya). answers_by_alias hanya ada bila form punya pertanyaan bernama pendek yang dijawab; kuncinya adalah nama pendek, sehingga paling mudah dipakai.
{
"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
}
}Bentuk nilai mengikuti jenis pertanyaan: angka tersimpan sebagai angka murni, tanggal dalam format ISO, telepon dalam format internasional, dan kotak centang sebagai daftar.
Header
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 | Kegunaan |
|---|---|
| X-Kakak-Event | Jenis kejadian. Saat ini selalu form.response. |
| X-Kakak-Delivery | Id kiriman. Sama di semua percobaan ulang, jadi pakai untuk menolak duplikat. |
| X-Kakak-Attempt | Percobaan ke berapa (1 sampai 4). |
| X-Kakak-Signature | t=<detik unix>,v1=<tanda tangan>. |
Memeriksa tanda tangan
Tanda tangan v1 adalah HMAC-SHA256 dalam heksadesimal, dengan kunci rahasia whsec_... (seluruh teksnya), atas teks <t>.<badan mentah>. Langkah di server penerima:
- 1. Ambil header
X-Kakak-Signature, pisahkan nilaitdanv1. - 2. Tolak bila
tlebih dari 5 menit dari jam server. - 3. Hitung HMAC-SHA256 dari
t + "." + badan mentahdengan rahasia. - 4. Bandingkan dengan
v1memakai perbandingan waktu-konstan. Tolak bila beda. - 5. Baru setelah itu ubah badan menjadi JSON.
// Node.js + Express. Baca badan MENTAH: tanda tangan dihitung dari teks persis yang dikirim.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const SECRET = process.env.KAKAKFORM_WEBHOOK_SECRET; // whsec_... dari ruang kerja Bagikan
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");
// Tolak kiriman yang lebih tua dari 5 menit (mencegah kiriman ulang oleh pihak lain).
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);
// Pakai X-Kakak-Delivery untuk menolak duplikat bila kiriman dicoba ulang.
console.log(req.get("X-Kakak-Delivery"), data.answers_by_alias);
res.sendStatus(200); // balas cepat; olah data berat di antrean sendiri
});
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() # badan mentah, 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 murni
$secret = getenv('KAKAKFORM_WEBHOOK_SECRET');
$body = file_get_contents('php://input'); // badan mentah
$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);Coba ulang dan batas waktu
- Penerima diberi waktu 5 detik per percobaan. Balas dengan status 2xx secepatnya, lalu olah data di belakang.
- Bila gagal karena galat jaringan, batas waktu, status 408, 425, 429, atau 5xx, kiriman dicoba ulang tiga kali dengan jeda sekitar 1, 3, dan 9 detik.
- Status 4xx lain dianggap penolakan dan tidak dicoba ulang.
- Pengalihan (3xx) tidak diikuti, tetapi dianggap terkirim. Ini membuat Google Apps Script yang membalas 302 tetap berfungsi.
- Kiriman berjalan di belakang layar, jadi responden tidak menunggu webhook selesai.
Contoh
Pendaftaran langsung masuk sistem akademik
Tim TI fakultas memasang webhook form pendaftaran asisten praktikum ke layanan internal berbahasa PHP. Layanan memeriksa tanda tangan, menolak id kiriman yang sudah pernah diproses, lalu menyimpan answers_by_alias.nim dan answers_by_alias.ipk ke tabel calon asisten.
