Lewati ke isi
kakak.aiform

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.

Di halaman ini

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. 1. Buka ruang kerja Bagikan, kartu Terima jawaban, bagian Webhook.
  2. 2. Tempel alamat penerima. Gunakan alamat https publik; alamat http diterima tetapi diberi peringatan karena tidak terenkripsi, dan alamat jaringan internal ditolak.
  3. 3. Simpan.
  4. 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.

Contoh badan kiriman
{
  "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 yang dikirim
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
HeaderKegunaan
X-Kakak-EventJenis kejadian. Saat ini selalu form.response.
X-Kakak-DeliveryId kiriman. Sama di semua percobaan ulang, jadi pakai untuk menolak duplikat.
X-Kakak-AttemptPercobaan ke berapa (1 sampai 4).
X-Kakak-Signaturet=<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. 1. Ambil header X-Kakak-Signature, pisahkan nilai t dan v1.
  2. 2. Tolak bila t lebih dari 5 menit dari jam server.
  3. 3. Hitung HMAC-SHA256 dari t + "." + badan mentah dengan rahasia.
  4. 4. Bandingkan dengan v1 memakai perbandingan waktu-konstan. Tolak bila beda.
  5. 5. Baru setelah itu ubah badan menjadi JSON.
Node.js (Express)
// 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)
# 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
// 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.

Ada yang kurang jelas? Tanyakan lewat tombol bantuan di pojok kanan bawah.