API & webhookide dokumentatsioon

Staaro pakub ühte avalikku integreerimispunkti — webhook-päästikut, mille kaudu sinu olemasolev süsteem (Zapier, Make, WooCommerce, oma serverid) saab käivitada SMS-tagasiside küsimuse. See dokument kirjeldab täpselt, kuidas seda kasutada.

Kogu tehniline viide (HTTP väljad, JSON võtmed, veakoodid, näidiskood) on inglise keeles, et hõlbustada kopeerimist olemasolevasse koodi. Selgitavad lõigud on eesti keeles.

Ülevaade

Webhook-päästik on lihtne HTTP-otspunkt, mille pihta sinu süsteem saadab POST päringu siis, kui klient on saanud teenuse ja on aeg küsida tagasisidet. Üks päring → üks järjekorda pandud SMS. Saatmise hetk võib olla kohe või edaspidi (vt scheduled_send_at).

Tüüpilised kasutusjuhud: Zapier/Make automatiseeringud, mis kuulavad teist süsteemi (broneering, arve, tellimus) ning käivitavad SMS-i; WooCommerce e-poed, kus tellimuse staatus “completed” käivitab tagasiside-küsimuse; oma rakendused, mis lisavad Staaro automatiseeritud kontuuri.

Saatmise piirangud (kvoot, opt-out, ettevõtte staatus) rakenduvad automaatselt. Sa ei pea oma poole pealt jälgima, kas klient on hindamisest loobunud — Staaro tagastab vastava staatuse ja jätab SMS-i saatmata.

Kiirstart

Eelduseks on Staaro konto ja aktiveeritud webhook-integratsioon. Mine sisse logituna lehele /integrations/webhook ning vajuta “Aktiveeri webhook”. Saad sealt webhook-tokeni (URL-i koostisosa) ja salajase võtme (HMAC-allkirja jaoks). Hoia mõlemad turvaliselt.

Minimaalne POST-päring (vaheta URL ja allkiri päris väärtuste vastu):

curl -X POST \
  https://api.staaro.ee/api/v1/triggers/webhook/YOUR_WEBHOOK_TOKEN \
  -H "Content-Type: application/json" \
  -H "X-Staaro-Signature: 9f1a...e3" \
  --data-binary '{"phone":"+37255555555","customer_name":"Mari Tamm"}'

Edu korral saad 202 Accepted ja JSON-vastuse, mis sisaldab järjekorda lisatud SMS-i ID-d ning planeeritud saatmisaega.

Autentimine

Igal päringul peab olema HMAC-SHA256 allkiri, mis on arvutatud toore päringukeha (request body) üle, kasutades sinu organisatsiooni salajast võtit. Aktsepteeritakse kahte päise nime — vali see, mis sobib sinu saatva süsteemiga:

• X-Staaro-Signature — heksadetsimaal-allkiri (lowercase hex). Kasuta seda kanoonilise “Staaro shape” JSON-keha jaoks (phone, customer_name jne).
• X-WC-Webhook-Signature — base64-allkiri. Kasuta seda, kui sinu allikas on WooCommerce — WC lisab selle päise automaatselt.

Veendu, et sinu kood allkirjastab täpselt sama baidijada, mille saadab HTTP päringuga (mitte näiteks pretty-printitud kuju). Kui rakendad mis tahes JSON-de-/reserializeerimist enne allkirja arvutamist, läheb allkiri katki.

Python (3.8+)

import hashlib, hmac, json, requests

WEBHOOK_TOKEN = "YOUR_WEBHOOK_TOKEN"
WEBHOOK_SECRET = b"YOUR_WEBHOOK_SECRET"

body = json.dumps({"phone": "+37255555555", "customer_name": "Mari Tamm"}).encode()
signature = hmac.new(WEBHOOK_SECRET, body, hashlib.sha256).hexdigest()

r = requests.post(
    f"https://api.staaro.ee/api/v1/triggers/webhook/{WEBHOOK_TOKEN}",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Staaro-Signature": signature,
    },
)
print(r.status_code, r.json())

Node.js (18+)

import crypto from "node:crypto";

const WEBHOOK_TOKEN = "YOUR_WEBHOOK_TOKEN";
const WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET";

const body = JSON.stringify({ phone: "+37255555555", customer_name: "Mari Tamm" });
const signature = crypto.createHmac("sha256", WEBHOOK_SECRET).update(body).digest("hex");

const res = await fetch(
  `https://api.staaro.ee/api/v1/triggers/webhook/${WEBHOOK_TOKEN}`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Staaro-Signature": signature,
    },
    body,
  }
);
console.log(res.status, await res.json());

PHP (8+)

<?php
$webhookToken = "YOUR_WEBHOOK_TOKEN";
$webhookSecret = "YOUR_WEBHOOK_SECRET";

$body = json_encode(["phone" => "+37255555555", "customer_name" => "Mari Tamm"]);
$signature = hash_hmac("sha256", $body, $webhookSecret);

$ch = curl_init("https://api.staaro.ee/api/v1/triggers/webhook/{$webhookToken}");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POSTFIELDS => $body,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Staaro-Signature: {$signature}",
  ],
]);
$response = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $response;

Päringu struktuur

HTTP-tasandil:

Kanooniline JSON keha (Staaro shape):

Vastuse koodid

Webhook tagastab kõik “andmehäiriku tüüpi” olukorrad (puudub telefoninumber, opt-out, kvoot täis jne) 200 OK staatusena, mitte 4xx-na. Põhjus: WooCommerce keelab webhooki automaatselt ära peale 5 järjestikust mitte-2xx vastust. Seega 4xx tähendab tõsist konfiguratsioonivea, mida sa pead parandama; 200 + skipped tähendab, et päring jõudis kohale, kuid SMS-i ei saadetud äriloogika tõttu.

Idempotentsus

Võrgu- ja töötlusvigadest taastumise jaoks tuleks samaks loetavat saatmist saata sama external_id väärtusega. Staaro hoiab kirja igast töödeldud ID-st ja tagastab korduva saatmise puhul 200 {duplicate: true} ilma uut SMS-i järjekorda lisamata.

Soovitame external_id tuletada allika-süsteemi stabiilsest identifikaatorist (nt order:12345, booking:abc-987). Kui sa external_id ei saada, kasutab Staaro varuvariandina päringukeha SHA-256 räsi, mis annab natuke nõrgema kaitse — samad väljad sama järjestusega → sama räsi.

Näited

Zapier — Webhooks by Zapier

Zapieri sisseehitatud Webhooks → POST sammust üksi ei piisa, sest Zapier ei oska iseseisvalt arvutada HMAC-allkirja. Lahendus: lisa enne webhook-sammu üks Code by Zapier samm, mis koostab allkirja.

// Code by Zapier (Run JavaScript)
const crypto = require("crypto");
const body = JSON.stringify({
  phone: inputData.phone,
  customer_name: inputData.name,
  external_id: `zapier:${inputData.run_id}`,
});
const signature = crypto
  .createHmac("sha256", inputData.secret)
  .update(body)
  .digest("hex");
return { body, signature };

Edasta järgmises sammus (Webhooks → POST) body päringukehana ja signature päises X-Staaro-Signature. Vali Payload Type: Raw, et Zapier ei reserialiseeriks JSON-it.

Node.js Express — vahepuhver, mis edastab Staarole

import express from "express";
import crypto from "node:crypto";

const app = express();
app.use(express.json());

const STAARO_TOKEN = process.env.STAARO_WEBHOOK_TOKEN;
const STAARO_SECRET = process.env.STAARO_WEBHOOK_SECRET;

app.post("/internal/review-trigger", async (req, res) => {
  const payload = {
    phone: req.body.customer.phone,
    customer_name: req.body.customer.first_name,
    external_id: `crm:order:${req.body.order_id}`,
  };
  const body = JSON.stringify(payload);
  const signature = crypto
    .createHmac("sha256", STAARO_SECRET)
    .update(body)
    .digest("hex");

  const staaroRes = await fetch(
    `https://api.staaro.ee/api/v1/triggers/webhook/${STAARO_TOKEN}`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Staaro-Signature": signature,
      },
      body,
    }
  );

  const json = await staaroRes.json();
  res.status(staaroRes.status).json(json);
});

app.listen(3000);

WooCommerce — administreerimisliides

WooCommerce saadab oma sisemise order.updated sündmuse koos ametliku X-WC-Webhook-Signature päisega. Sa ei pea koodi kirjutama — vajaliku konfigureerimise teed admin-liideses.

1. WordPress admin → WooCommerce → Settings → Advanced → Webhooks → Add webhook.
2. Name: Staaro review trigger. Status: Active. Topic: Order updated. Delivery URL: https://api.staaro.ee/api/v1/triggers/webhook/{webhook_token}.
3. Secret: sama salajane võti, mille Staaro sulle näitas/integrations/webhook lehel.
4. API Version: WP REST API Integration v3.

Staaro tunneb WooCommerce'i päringukeha automaatselt ära ning kasutab tellimuse billing.phone ja billing.first_name välju. Tellimuse staatuse completed peale lisab Staaro SMS-i järjekorda; staatuste cancelled / refunded / failed / trash peale tühistab Staaro sama tellimuse veel saatmata SMS-i.

Piirangud ja kvoot

• Päringukiirus: 60 päringut minutis organisatsiooni kohta. Üle piiri → 429 Too Many Requests.
• SMS-kvoot: Staaro paketis 100 SMS/kuus, Staaro Pro paketis 300 SMS/kuus. Üle piiri → 200 {skipped: "quota_exhausted"}.
• Telefoninumber: peab olema E.164 formaadis (alustab +, riigikood, number). Vale formaat → 200 {skipped: "invalid_phone"}.
• Opt-out: kui klient on varem loobunud, ei saadeta SMS-i ja tagastatakse 200 {skipped: "opted_out"}.
• Konto staatus: kui arve on tasumata ja konto on peatatud, ei saadeta SMS-e ja tagastatakse 200 {skipped: "suspended"}.

Need piirangud on samal ajal ka väärkasutuse piiramise mehhanism — isegi kui sinu salajane võti peaks lekkima, on rünnaku “katuseks” kvoot ja päringukiirus. Sa maksad SMS-ide eest oma paketi piires; rohkem rünnataja saata ei saa.

Turvalisus

Soovitused, mida järgida, et salajane võti ei satuks valedesse kätesse:

• Käsitle salajast võtit nagu parooli. Ära salvesta seda Giti, ära paigutamine jagatud vestlustesse, ära logi raw X-Staaro-Signature väärtusi.
• Allkirjasta ainult serveri poolelt. Mitte kunagi brauserist ega mobiilirakenduse koodist — seal oleks salajane võti kasutaja jaoks nähtav.
• Roteeri salajast võtit kohe lekke kahtluse korral. Mine /integrations/webhook lehele ja vajuta “Genereeri uus salajane võti”. Vana võti lakkab kohe töötamast — uue võtmega allkirjastamine peab algama samal hetkel.
• Hoia saatja IP-d stabiilsed. Edaspidi võib tulla IP-piirang-režiim; juba praegu fikseeritud väljuvad IP-d teevad hilisema lisamise lihtsamaks.
• Tee allkirja võrdlus konstantse aja jooksul. Kui kirjutad ise valideerijat (nt Staaro-lt kuldselt Staarole — vt §7 vahepuhver), kasuta hmac.compare_digest või vaste, mitte tavalist string-võrdlust.

Tugi

Küsimused, vea-raportid ja integratsioonimured: võta meiega ühendust info@staaro.ee. Kõige kiirema vastuse saad, kui kirja juurde lisad reprodutseeritava curl käsu (ilma salajast võtit ega päris telefoninumbrit avaldamata) ning vastuse staatuskoodi.

Kahtlustad lekkinud salajast võtit? Pöördu kohe info@staaro.ee — peatame integratsiooni ja aitame võtme rotatsiooniga.

VIIMATI MUUDETUD · 11/05/2026 · KRAL HOLDINGS OÜ · 17085029