Webhooks
Webhook addresses are set up by the shop in Pengaturan → Webhook (Settings → Webhooks), or by your integration itself through the API (flow 6), with the chosen events. The signing secret is shown once.
document_read.succeeded | A document read finished. data: runId, documentTypeId, status, provider, model, clientReference. |
document_read.failed | A document read failed. data: runId, documentTypeId, status, provider, model, error (in English), clientReference. |
blog_generation.succeeded | An article finished writing. data: generationId, status, clientReference. |
blog_generation.failed | An article failed to write. data: generationId, status, errorCode, clientReference. |
image_generation.succeeded | An image finished. data: generationId, status, clientReference. |
image_generation.failed | An image failed. data: generationId, status, errorCode, clientReference. |
top_up.approved | A top-up was approved, and the balance has gone up. data: topUpId, reference, amount (what was credited to the balance, whole rupiah; can be less than requested if the transfer was short). |
top_up.rejected | A top-up was rejected. data: topUpId, reference, reason. |
balance.low | The balance fell below the warning set (PUT /v1/billing/low-balance). Sent once each time the balance falls past it, and only again after the balance rises above it. The shop's people are told by email at most once per 12 hours. data: balance, threshold, currency. |
webhook.test | A test from the "Kirim uji coba" (Send test) button on the shop's screen, or POST /v1/webhooks/{id}/test. |
The body of every delivery
{
"id": "6f1c…", // the same on every retry; ignore ones already processed
"type": "document_read.succeeded",
"createdAt": "2026-10-14T09:30:00.000Z",
"companyId": "…",
"data": { "runId": "…", "documentTypeId": "…", "status": "succeeded" }
}
Checking the signature
Every delivery carries the headers Tekomata-Event, Tekomata-Delivery, and Tekomata-Signature: t=<unix seconds>,v1=<hex>. v1 is HMAC-SHA256(secret, "<t>.<raw body>"). Compute it from the raw bytes before parsing, compare in constant time, and reject a t older than 5 minutes.
JavaScript (Node)
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret)
.update(`${t}.${rawBody}`).digest("hex");
const given = Buffer.from(v1 ?? "");
// timingSafeEqual throws on unequal lengths; a missing or short v1 is false.
return given.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), given);
}
PHP
function verify(string $raw, string $header, string $secret): bool {
parse_str(str_replace(',', '&', $header), $p);
if (abs(time() - (int)$p['t']) > 300) return false;
return hash_equals(hash_hmac('sha256', $p['t'] . '.' . $raw, $secret), $p['v1']);
}
Python
import hashlib, hmac, time
def verify(raw: bytes, header: str, secret: str) -> bool:
p = dict(part.split("=", 1) for part in header.split(","))
if abs(time.time() - int(p["t"])) > 300:
return False
expected = hmac.new(secret.encode(), p["t"].encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, p["v1"])
Responding and retries
- Answer 2xx within 10 seconds, then do the work afterwards. A slow answer counts as a failure.
- A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours, and 24 hours, then it stops. Redirects are not followed.
- The same delivery can arrive more than once, and out of order. Use the id in the body to ignore ones already processed.
- After 50 failures in a row, the address is switched off and the shop's screen says why.
- The address must be https and reachable from the internet.