For developers

Tekomata API

Read a photo or PDF into data with the AI model of your choice, in a standard form, with the page and the place on the document where each value was read; write blog posts with AI, and hear when each is done by webhook. Read the balance and top it up by bank transfer. Paid from the shop's Tekomata credit — try it below with your integration's access token.

6. Setting up your own webhook

Your integration manages its webhook addresses through the API.

Permissions: webhooks:manage

  1. 1
    Your systemPOST /v1/webhooks

    Send "url" (https, reachable from the internet) and "events". The response is that address and the signing "secret", shown once.

  2. 2
    Your systemPOST /v1/webhooks/{id}/test

    Send a webhook.test, then see the result in GET /v1/webhooks/{id}/deliveries.

  3. 3
    Tekomata

    Every chosen event is sent to that address, signed with its secret.

  4. 4
    Your systemPATCH /v1/webhooks/{id}

    Change the address or its events, or switch it off with "isActive": false. POST /v1/webhooks/{id}/secret makes a new secret.

  • An integration sees and changes only the addresses it created itself; addresses the shop set up are not visible.
  • The events you can choose follow the integration's permissions: document_read.* with documents:read, blog_generation.* with blog:generate, image_generation.* with images:generate, top_up.* and balance.low with billing:read. Anything else is refused 422 event_not_allowed. An address stops receiving those events as soon as the integration loses the permission or is switched off.

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.succeededA document read finished. data: runId, documentTypeId, status, provider, model, clientReference.
document_read.failedA document read failed. data: runId, documentTypeId, status, provider, model, error (in English), clientReference.
blog_generation.succeededAn article finished writing. data: generationId, status, clientReference.
blog_generation.failedAn article failed to write. data: generationId, status, errorCode, clientReference.
image_generation.succeededAn image finished. data: generationId, status, clientReference.
image_generation.failedAn image failed. data: generationId, status, errorCode, clientReference.
top_up.approvedA 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.rejectedA top-up was rejected. data: topUpId, reference, reason.
balance.lowThe 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.testA 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.