Webhooks

În loc să întrebi API-ul din minut în minut, primești un POST când apare ceva nou. Adrese pe plan: 2 pe Creator, 10 pe Pro, 50 pe Business.

Evenimente

news.publishedO știre nouă cu gravitatea cel puțin cât min_gravity al adresei, implicit 50.
law.digestDigestul legislativ al zilei este gata.
fuel.capANRE a publicat un plafon nou.
rates.updatedBNM a publicat cursul zilei.
price.changedPrețul unui produs urmărit s-a schimbat într-un magazin. O adresă listează până la 500 de produse în items. Comparația rulează la fiecare 30 de minute.

Ce primești

Un POST cu JSON și două antete: Satelit-Event și Satelit-Signature.

POST

{
  "id": "evt_01J9ZK3Q",
  "type": "price.changed",
  "created_at": "2026-11-02T13:30:00+02:00",
  "data": {
    "item": 18342,
    "store": "kaufland",
    "old": 17.19,
    "new": 16.05,
    "at": "2026-11-02T13:12:00+02:00"
  }
}

Verifică semnătura

Antetul arată așa: t=<unix>,v1=<semnătura>. Semnătura este HMAC-SHA256 cu secretul adresei, peste t.body: momentul, un punct și corpul exact, neschimbat. Respinge un moment mai vechi de 5 minute, ca să oprești reluările.

Secretul apare o singură dată, când creezi adresa în panou. Îl ții pe serverul tău.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as it arrived, before any JSON parsing
export function verify(rawBody, header, secret, tolerance = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > tolerance) return false;
  const expected = Buffer.from(createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"));
  const given = Buffer.from(parts.v1 ?? "");
  return expected.length === given.length && timingSafeEqual(expected, given);
}

import hashlib
import hmac
import time


# raw_body: the request body exactly as it arrived, as bytes
def verify(raw_body, header, secret, tolerance=300):
    parts = dict(p.split("=", 1) for p in header.split(","))
    t = int(parts.get("t", 0))
    if abs(time.time() - t) > tolerance:
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

<?php
// $rawBody: the request body exactly as it arrived: file_get_contents("php://input")
function verify(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(",", $header) as $part) {
        [$k, $v] = array_pad(explode("=", $part, 2), 2, "");
        $parts[$k] = $v;
    }
    $t = (int) ($parts["t"] ?? 0);
    if (abs(time() - $t) > $tolerance) {
        return false;
    }
    $expected = hash_hmac("sha256", $t . "." . $rawBody, $secret);
    return hash_equals($expected, $parts["v1"] ?? "");
}

Cum se livrează

Doar HTTPS, spre adrese publice. Redirecționările nu sunt urmate.
Așteptăm 5 secunde. Un răspuns 2xx înseamnă primit.
Trei încercări în 15 minute.
După 20 de eșecuri la rând adresa se oprește. O pornești din nou din panou.
Fiecare eveniment are un id. Păstrează-l, ca să ignori dublurile.

Testează

Din panou trimiți un eveniment de test și vezi ultimele livrări, cu statusul lor.

Webhooks