Webhooks

Prejmite obvestila v realnem času, ko se zgodijo dogodki.

Pregled

Webhooks vam omogočajo:

• Takojšnja obvestila o dogodkih
• Avtomatizacijo delovnih tokov
• Sinhronizacijo z zunanjimi sistemi
• Gradnjo reaktivnih integracij

Zahteva paketa

Dostop do webhook zahteva paket, ki vključuje funkcije API.

Kako webhooks delujejo

1. Konfigurirate URL naslova
2. Izberete dogodke za naročnino
3. Ko se zgodijo dogodki, pošljemo HTTP POST zahteve
4. Vaš strežnik obdela vsebino
5. Odgovorite s statusom 2xx

Razpoložljivi dogodki

Dogodek	Opis
photo_request.created	Ustvarjena nova foto zahteva
photo_request.first_viewed	Zahteva prvič ogledana
photo_submission.created	Fotografije oddane (trajne povezave)
photo_request.submitted	Enkratna zahteva zaključena
photo_request.expired	Zahteva potekla brez oddaje
photo_submission.dropbox_synced	Fotografija sinhronizirana v Dropbox s povezavo za skupno rabo

Ustvarjanje webhooka

Koraki

1. Pojdite na Webhooks v stranski vrstici
2. Kliknite Ustvari webhook
3. Vnesite opisno ime
4. Vnesite URL vašega naslova
5. Izberite dogodke za naročnino
6. Preklopite Aktiven (privzeto: vključeno)
7. Kliknite Ustvari

Zahteve za naslov

Zahteva	Vrednost
Protokol	Potreben HTTPS
Dostopnost	Javni internet
Odgovor	Statusna koda 2xx
Časovna omejitev	Največ 30 sekund

Zasebna omrežja

Zasebni in notranji omrežni naslovi (localhost, 10.x.x.x, 192.168.x.x) niso dovoljeni.

Webhook vsebina

Format zahteve

POST /vas-naslov HTTP/1.1
Host: vas-streznik.com
Content-Type: application/json
X-Webhook-Signature: sha256=abc123...
X-Webhook-ID: wh_123456
X-Webhook-Timestamp: 1609459200

Struktura vsebine

{
  "event": "photo_request.submitted",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "req_abc123",
    "type": "one_time",
    "instructions": "Pošljite fotografije vozila",
    "photos": [
      {
        "id": "photo_xyz789",
        "url": "https://...",
        "slot_instructions": "Pogled spredaj",
        "metadata": {
          "gps_lat": 45.1234,
          "gps_lng": 12.5678,
          "captured_at": "2024-01-15T10:28:00Z"
        }
      }
    ],
    "submitted_at": "2024-01-15T10:30:00Z"
  }
}

Preverjanje podpisa

Zakaj preverjati

Preverjajte podpise webhookov za zagotovitev:

• Zahteva je prišla od Visiono
• Vsebina ni bila spremenjena
• Preprečevanje napadov s ponovitvijo

Glava podpisa

X-Webhook-Signature: sha256=abc123def456...

Koraki preverjanja

// PHP primer
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'vasa-webhook-skrivnost';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Neveljaven podpis');
}

// Node.js primer
const crypto = require('crypto');

const payload = JSON.stringify(req.body);
const signature = req.headers['x-webhook-signature'];
const secret = process.env.WEBHOOK_SECRET;

const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
  return res.status(401).send('Neveljaven podpis');
}

Upravljanje webhookov

Preizkus webhooka

Pošljite testni dogodek:

1. Kliknite Preizkusi na webhooku
2. Potrdite dejanje
3. Preverite status odgovora
4. Če ni uspelo, poglejte v dnevnike

Ogled dnevnikov

Oglejte si zgodovino dostav:

1. Kliknite Dnevniki na webhooku
2. Oglejte si nedavne dostave
3. Preverite status in odgovor
4. Odpravite napake

Podrobnosti dnevnika

Vsak dnevnik prikazuje:

• Vrsta dogodka
• Časovni žig
• Status odgovora
• Čas odgovora
• Telo zahteve/odgovora (za odpravljanje napak)

Regeneracija skrivnosti

Pridobite novo skrivnost za podpisovanje:

1. Kliknite Regeneriraj skrivnost
2. Potrdite dejanje
3. Takoj kopirajte novo skrivnost
4. Posodobite svoj strežnik

Najprej posodobite strežnik

Po regeneraciji stara skrivnost preneha delovati. Posodobite svojo kodo za preverjanje pred regeneracijo.

Deaktivacija webhooka

Začasno prenehajte prejemati dogodke:

1. Kliknite Deaktiviraj
2. Potrdite dejanje
3. Dogodki se ne pošiljajo več
4. Ponovno aktivirajte, ko ste pripravljeni

Brisanje webhooka

Trajno odstranite:

1. Kliknite Izbriši
2. Potrdite dejanje
3. Vsi dnevniki so izbrisani

Politika ponovitev

Samodejne ponovitve

Neuspele dostave se ponovijo:

Poskus	Zamuda
1	Takojšnja
2	1 minuta
3	5 minut
4	30 minut
5	2 uri

Kriteriji neuspeha

Dostava ne uspe, če:

• Časovna omejitev povezave (30s)
• Odgovor ni 2xx
• Omrežna napaka
• SSL napaka

Po maksimalnih ponovitvah

Če vse ponovitve ne uspejo:

• Dogodek je označen kot neuspel
• Zabeležen za pregled
• Ni nadaljnjih poskusov

Najboljše prakse

Zasnova naslova

• Odgovorite hitro (< 5 sekund)
• Po potrebi obdelajte asinhrono
• Takoj vrnite 2xx
• Obvladajte idempotentnost

Obravnava napak

// Priporočen vzorec
app.post('/webhook', async (req, res) => {
  // Najprej preverite podpis
  if (!verifySignature(req)) {
    return res.status(401).send('Neveljavno');
  }

  // Takoj potrdite prejem
  res.status(200).send('OK');

  // Obdelajte asinhrono
  processWebhookAsync(req.body);
});

Idempotentnost

Dogodki se lahko pošljejo več kot enkrat. Obvladajte dvojnike:

// Preverite, ali je že obdelano
const eventId = req.headers['x-webhook-id'];
if (await isProcessed(eventId)) {
  return res.status(200).send('Že obdelano');
}

// Obdelajte in označite kot obravnavano
await processEvent(req.body);
await markProcessed(eventId);

Spremljanje

• Beležite vse dohodne webhooks
• Opozorite ob napakah
• Spremljajte čase odgovorov
• Sledite obsegom dogodkov

Odpravljanje težav

Ne prejemate dogodkov

1. Preverite, ali je webhook aktiven
2. Preverite, ali je URL naslova pravilen
3. Zagotovite, da HTTPS deluje
4. Preverite, ali je strežnik dostopen
5. Preverite izbrane dogodke

Neujemanje podpisa

1. Uporabite pravilno skrivnost
2. Primerjajte celotno vsebino (ne razčlenjeno)
3. Preverite težave s kodiranjem
4. Preverite HMAC algoritem (SHA256)

Časovne omejitve

1. Zmanjšajte čas obdelave
2. Takoj potrdite prejem
3. Obdelajte asinhrono
4. Preverite vire strežnika

Ogled neuspelih dostav

1. Pojdite na dnevnike webhooka
2. Filtrirajte po statusu (neuspelo)
3. Oglejte si podrobnosti zahteve/odgovora
4. Popravite in znova preizkusite

Omejitve webhookov

Glede na paket

Paket	Maks. webhookov
Profesionalni	5 webhookov
Poslovni	Neomejeno

Omejitve hitrosti

Omejitev	Vrednost
Dogodki na minuto	100
Velikost vsebine	1 MB

Povezane strani

• API ključi - API avtentikacija
• API referenca - Celotna API dokumentacija
• Integracije - Vnaprej zgrajene integracije