Webhooki
Z FastComments je mogoče poklicati API endpoint vsakič, ko je komentar dodan, posodobljen ali odstranjen iz našega sistema.
To dosežemo z asinhronimi webhooks prek HTTP/HTTPS.
Kaj so webhooki 
Webhook je mehanizem, ali integracija, med dvema sistemoma, kjer "producent" (FastComments) sproži dogodek ki ga "potrošnik" (Vi) prejme prek API klica.
Podprti dogodki in viri
FastComments podpira webhooks le za vir Comment.
Podpiramo webhooks za ustvarjanje komentarjev, odstranjevanje in posodobitve.
Vsak od teh se v našem sistemu šteje kot ločen dogodek in kot tak ima različne semantike in strukture za dogodke webhooka.
Nastavitev za lokalni razvoj
For Local development, use a tool like ngrok.
In order to simplify keeping the system secure, local development follows the same process as setting up and securing other environments.
Step 1: Add "localhost" to domains in your account.
Add "localhost" as a domain here.
Step 2: Pick an API Key
We're going to be adding webhook configuration for your domain, so we'll need an API key. You can do that here.
Under "Associate with domain" - select your "localhost" domain.
OPOMBA: Alternatively, you can use one API Secret for all testing activity and staging environments. Simply add an API Secret for "All Domains", and give it a name like "test".
Ensure you have an API Secret defined for your production domain(s). Events for all other domains will use the wildcard (testing) secret.
Step 3: Add Your Webhook
While running ngrok or similar tool, set the value for "localhost" here.
When clicking Send Test Payload, we will send two test events to check that you validate the API key.
Once it validates, hit Save.
Step 4: Add A Comment
Now you can add, edit, or delete comments and should see us call your local development machine with the events, using your testing API key. There may be up to 30 seconds delay for the events to reach your machine.
Nastavitev
Follow the same steps for localhost as you would production. Ensure you have production domains and API Secrets setup.
First, navigate to the Skrbnik webhookov. This is accessible via Manage Data -> Webhooks.
The configuration page appears as follows:
In this page you can specify endpoints for each type of comment event.
For each type of event, be sure to click Send Test Payload to ensure you've set up your integration correctly. See the next section, "Testing", for details.
Testiranje
V skrbniškem vmesniku Webhooks so gumbi Send Test Payload za vsako vrsto dogodka (Create, Update, Delete). Dogodki Create in Update pošljejo testni objekt WebhookComment, medtem ko bo pri testiranju Delete poslan testni telo zahteve, ki vsebuje le ID.
Preverjanje obremenitev
Pri testiranju vaše webhook integracije preverite, ali dohodni zahtevki vsebujejo naslednje glave:
token- Vaša API skrivnostX-FastComments-Timestamp- Unix časovni žig (v sekundah)X-FastComments-Signature- HMAC-SHA256 podpis
Uporabite preverjanje HMAC podpisa, da zagotovite pristnost podatkov.
Orodja za testiranje
Med razvojem lahko za pregled vsebine dohodnih webhook zahtevkov uporabite orodja, kot so webhook.site ali ngrok.
Vrste dogodkov
- Create Event: Sproži se, ko je ustvarjen nov komentar. Privzeta metoda: PUT
- Update Event: Sproži se, ko je komentar urejen. Privzeta metoda: PUT
- Delete Event: Sproži se, ko je komentar izbrisan. Privzeta metoda: DELETE
Vsak dogodek vključuje polne podatke komentarja v telesu zahtevka (glejte Strukture podatkov za format podatkov).
Strukture podatkov
Edina struktura, poslana prek webhookov, je objekt WebhookComment, predstavljen v TypeScriptu spodaj.
Struktura objekta WebhookComment
Struktura dogodka "Create"
Request body dogodka "create" je objekt WebhookComment.
Struktura dogodka "Update"
Request body dogodka "update" je objekt WebhookComment.
Struktura dogodka "Delete"
Request body dogodka "delete" je objekt WebhookComment.
Sprememba z dne 14. novembra 2023
Pred tem je request body dogodka "delete" vseboval samo id komentarja. Zdaj vsebuje celoten komentar v času brisanja.
Run Ko so uporabniki omenjeni v komentarju, se informacije shranijo v seznamu z imenom mentions. Vsak objekt v tem seznamu ima naslednjo strukturo.
Run HTTP Methods
Na administratorskem vmesniku lahko konfigurirate HTTP metodo za vsako vrsto webhook dogodka:
- Create Event: POST ali PUT (privzeto: PUT)
- Update Event: POST ali PUT (privzeto: PUT)
- Delete Event: DELETE, POST ali PUT (privzeto: DELETE)
Ker vse zahteve vsebujejo ID, sta operaciji Create in Update po privzetku idempotentni (PUT). Ponovitev iste zahteve Create ali Update ne bi smela ustvariti podvojenih objektov na vaši strani.
Request Headers
Vsaka webhook zahteva vključuje naslednje glave:
| Header | Description |
|---|---|
Content-Type | application/json |
token | Vaš API skrivni ključ |
X-FastComments-Timestamp | Unix časovni žig (sekunde), ko je bila zahteva podpisana |
X-FastComments-Signature | HMAC-SHA256 podpis (sha256=<hex>) |
Za informacije o preverjanju HMAC podpisa glejte Varnost in API žetoni.
Varnost in API žetoni
FastComments webhook zahtevki vsebujejo več mehanizmov za overjanje za zagotavljanje varnosti.
Poslane glave
| Glava | Opis |
|---|---|
token | Vaš API skrivni ključ (za združljivost z starejšimi različicami) |
X-FastComments-Timestamp | Unix časovni žig (v sekundah), ko je bil zahtevek podpisan |
X-FastComments-Signature | HMAC-SHA256 podpis vsebine |
Preverjanje HMAC podpisa (priporočeno)
Močno priporočamo preverjanje HMAC podpisa, da zagotovite, da so podatki webhooka avtentični in da z njimi ni bilo manipulirano.
Oblika podpisa: sha256=<hex-encoded-signature>
Kako se izračuna podpis:
- Združi:
timestamp + "." + JSON_payload_body - Izračunajte HMAC-SHA256 z vašim API skrivnim ključem kot ključem
- Hex-kodirajte rezultat
Primer preverjanja (Node.js)
const crypto = require('crypto');
function verifyWebhookSignature(req, apiSecret) {
const timestamp = req.headers['x-fastcomments-timestamp'];
const signature = req.headers['x-fastcomments-signature'];
if (!timestamp || !signature) {
return false;
}
// Preveri, ali je časovni žig svež (v 5 minutah)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return false; // Preprečevanje ponovitvenega napada
}
// Preveri podpis
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', apiSecret)
.update(`${timestamp}.${payload}`)
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Primer preverjanja (Python)
import hmac
import hashlib
import time
import json
def verify_webhook_signature(headers, body, api_secret):
timestamp = headers.get('X-FastComments-Timestamp')
signature = headers.get('X-FastComments-Signature')
if not timestamp or not signature:
return False
# Preveri, ali je časovni žig svež
now = int(time.time())
if abs(now - int(timestamp)) > 300:
return False
# Preveri podpis
payload = json.dumps(body, separators=(',', ':'))
message = f"{timestamp}.{payload}"
expected = hmac.new(
api_secret.encode(),
message.encode(),
hashlib.sha256
).hexdigest()
return signature == f"sha256={expected}"Primer preverjanja (PHP)
function verifyWebhookSignature($headers, $body, $apiSecret) {
$timestamp = $headers['X-FastComments-Timestamp'] ?? null;
$signature = $headers['X-FastComments-Signature'] ?? null;
if (!$timestamp || !$signature) {
return false;
}
// Preveri, ali je časovni žig svež (v 5 minutah)
$now = time();
if (abs($now - intval($timestamp)) > 300) {
return false;
}
// Preveri podpis
$payload = json_encode($body, JSON_UNESCAPED_SLASHES);
$message = $timestamp . '.' . $payload;
$expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);
return hash_equals($expectedSignature, $signature);
}Zastarelo overjanje
Glava token, ki vsebuje vaš API skrivni ključ, se še vedno pošilja zaradi združljivosti z starejšimi različicami. Vendar priporočamo prehod na preverjanje preko HMAC zaradi boljše varnosti, saj ščiti pred ponovitvenimi napadi.
Kako deluje in obravnavanje ponovnih poizkusov
Vse spremembe objekta Comment v sistemu sprožijo dogodek, ki se znajde v vrsti.
Prvotni webhook dogodek je običajno poslan v šestih sekundah po nastanku vira dogodka.
To vrsto lahko spremljate v Webhooks admin v primeru, da vaš API preneha delovati.
Če zahteva do vašega API ne uspe, jo bomo ponovno uvrstili v vrsto po urniku.
Ta urnik je 1 Minute * the retry count. Če klic ne uspe enkrat, bo poskus ponovljen čez
minuto. Če ne uspe dvakrat, bo nato počakal dve minuti, in tako naprej. To je zato, da ne
preobremenimo vašega API, če imate izpade zaradi obremenitve.
Webhooks je mogoče preklicati na stran z dnevniki.
Za zaključek
To zaključuje našo dokumentacijo o Webhookih.
Upamo, da boste integracijo FastComments Webhookov našli enostavno za razumevanje in hitro za nastavitev.
Če menite, da ste odkrili kakšne vrzeli v naši dokumentaciji, nam sporočite spodaj.