Webhooks

Primajte obavijesti u stvarnom vremenu kada se događaji dogode.

Pregled

Webhooks vam omogućuju:

• Dobivanje trenutnih obavijesti o događajima
• Automatizaciju tijekova rada
• Sinkronizaciju s vanjskim sustavima
• Izgradnju reaktivnih integracija

Zahtjev plana

Pristup webhooksima zahtijeva plan koji uključuje API značajke.

Kako webhooks rade

1. Konfigurirate URL krajnje točke
2. Odaberete događaje za pretplatu
3. Kada se događaji dogode, šaljemo HTTP POST zahtjeve
4. Vaš poslužitelj obrađuje payload
5. Odgovarate sa 2xx statusom

Dostupni događaji

Događaj	Opis
photo_request.created	Novi zahtjev za fotografije kreiran
photo_request.first_viewed	Zahtjev pregledan prvi put
photo_submission.created	Fotografije poslane (Trajni linkovi)
photo_request.submitted	Jednokratni zahtjev dovršen
photo_request.expired	Zahtjev istekao bez slanja
photo_submission.dropbox_synced	Fotografija sinkronizirana na Dropbox s dijeljenom poveznicom

Kreiranje webhooka

Koraci

1. Idite na Webhooks u bočnoj traci
2. Kliknite Kreiraj webhook
3. Unesite opisni naziv
4. Navedite URL krajnje točke
5. Odaberite događaje za pretplatu
6. Uključite Aktivan (zadano: uključeno)
7. Kliknite Kreiraj

Zahtjevi krajnje točke

Zahtjev	Vrijednost
Protokol	HTTPS obavezan
Dostupnost	Javni internet
Odgovor	2xx statusni kod
Timeout	Maksimalno 30 sekundi

Privatne mreže

Privatne i interne mrežne adrese (localhost, 10.x.x.x, 192.168.x.x) nisu dozvoljene.

Webhook payload

Format zahtjeva

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

Struktura payloada

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

Verifikacija potpisa

Zašto verificirati

Verificirajte webhook potpise da osigurate:

• Zahtjev je došao od Visiona
• Payload nije modificiran
• Spriječite replay napade

Zaglavlje potpisa

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

Koraci verifikacije

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

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

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Nevažeći potpis');
}

// Node.js primjer
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('Nevažeći potpis');
}

Upravljanje webhooksima

Testiraj webhook

Pošaljite testni događaj:

1. Kliknite Test na webhooku
2. Potvrdite akciju
3. Provjerite status odgovora
4. Pregledajte u zapisnicima ako nije uspjelo

Pregledaj zapisnike

Pogledajte povijest isporuke:

1. Kliknite Zapisnici na webhooku
2. Pregledajte nedavne isporuke
3. Provjerite status i odgovor
4. Otklonite pogreške

Detalji zapisnika

Svaki zapis prikazuje:

• Vrstu događaja
• Vremensku oznaku
• Status odgovora
• Vrijeme odgovora
• Tijelo zahtjeva/odgovora (za otklanjanje pogrešaka)

Regeneriraj tajnu

Dobijte novu tajnu za potpisivanje:

1. Kliknite Regeneriraj tajnu
2. Potvrdite akciju
3. Odmah kopirajte novu tajnu
4. Ažurirajte svoj poslužitelj

Prvo ažurirajte poslužitelj

Nakon regeneriranja, stara tajna prestaje raditi. Ažurirajte svoj kod za verifikaciju prije regeneriranja.

Deaktiviraj webhook

Privremeno prestanite primati događaje:

1. Kliknite Deaktiviraj
2. Potvrdite akciju
3. Događaji se više ne šalju
4. Reaktivirajte kada budete spremni

Obriši webhook

Trajno uklonite:

1. Kliknite Obriši
2. Potvrdite akciju
3. Svi zapisnici su obrisani

Politika ponovnih pokušaja

Automatski ponovni pokušaji

Neuspjele isporuke se ponavljaju:

Pokušaj	Odgoda
1	Odmah
2	1 minuta
3	5 minuta
4	30 minuta
5	2 sata

Kriteriji neuspjeha

Isporuka ne uspijeva ako:

• Timeout veze (30s)
• Odgovor nije 2xx
• Mrežna greška
• SSL greška

Nakon maksimalnih pokušaja

Ako svi pokušaji ne uspiju:

• Događaj se označava kao neuspješan
• Zapisano za pregled
• Nema daljnjih pokušaja

Najbolje prakse

Dizajn krajnje točke

• Odgovorite brzo (< 5 sekundi)
• Obradite asinkrono ako je potrebno
• Vratite 2xx odmah
• Rukujte idempotentno

Rukovanje greškama

// Preporučeni obrazac
app.post('/webhook', async (req, res) => {
  // Prvo verificirajte potpis
  if (!verifySignature(req)) {
    return res.status(401).send('Nevažeće');
  }

  // Potvrdite odmah
  res.status(200).send('OK');

  // Obradite asinkrono
  processWebhookAsync(req.body);
});

Idempotentnost

Događaji se mogu poslati više puta. Rukujte duplikatima:

// Provjerite je li već obrađeno
const eventId = req.headers['x-webhook-id'];
if (await isProcessed(eventId)) {
  return res.status(200).send('Već obrađeno');
}

// Obradite i označite kao obrađeno
await processEvent(req.body);
await markProcessed(eventId);

Nadzor

• Zabilježite sve dolazne webhookove
• Upozorite na neuspjehe
• Pratite vrijeme odgovora
• Pratite volumene događaja

Rješavanje problema

Ne primam događaje

1. Provjerite je li webhook aktivan
2. Provjerite je li URL krajnje točke ispravan
3. Osigurajte da HTTPS radi
4. Provjerite je li poslužitelj dostupan
5. Provjerite odabrane događaje

Nepodudaranje potpisa

1. Koristite ispravnu tajnu
2. Usporedite potpuni payload (ne parsirani)
3. Provjerite probleme s kodiranjem
4. Provjerite HMAC algoritam (SHA256)

Timeouti

1. Smanjite vrijeme obrade
2. Potvrdite odmah
3. Obradite asinkrono
4. Provjerite resurse poslužitelja

Pregledaj neuspjele isporuke

1. Idite na zapise webhooka
2. Filtrirajte po statusu (neuspješno)
3. Pregledajte detalje zahtjeva/odgovora
4. Ispravite i ponovno testirajte

Ograničenja webhookova

Po planu

Plan	Maks. webhookova
Professional	5 webhookova
Enterprise	Neograničeno

Ograničenja brzine

Ograničenje	Vrijednost
Događaja po minuti	100
Veličina payloada	1 MB

Povezane stranice

• API ključevi - API autentifikacija
• API referenca - Potpuna API dokumentacija
• Integracije - Gotove integracije