Webhook-ovi

Format zaglavlja

Platico-Signature: t=<unix_timestamp>,v1=<hex hmac-sha256>

Potpis pokriva t.payload gde je payload TAČNE bajtove tela zahteva (ne JSON-parsovano).

Verifikacija sa Node SDK

import express from 'express'
import Platico from 'platico'

const platico = new Platico(process.env.PLATICO_API_KEY!)
const app = express()

// KRITIČNO: express.raw, NIKADA express.json za webhook rutu.
// json() re-serijalizuje body i HMAC više ne odgovara.
app.post(
  '/webhooks/platico',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    try {
      const event = platico.webhooks.constructEvent(
        req.body,                              // Buffer
        req.header('Platico-Signature') ?? '',
        process.env.PLATICO_WEBHOOK_SECRET!,
      )
      // event je verifikovan + parsiran
      switch (event.type) {
        case 'payment_intent.succeeded':
          // proveri narudžbu kao plaćenu
          break
        case 'charge.dispute.created':
          // alert tim za sporove
          break
      }
      res.sendStatus(200)
    } catch (err) {
      res.sendStatus(400)
    }
  },
)

Tipovi grešaka

SDK baca tri različite klase grešaka za webhook verifikaciju:

• WebhookSignatureInvalidError — potpis ne odgovara. Potencijalni napad (ili pogrešan secret). Alert.
• WebhookTimestampStaleError — timestamp je stariji od tolerancije (podrazumevano 300s). Verovatno clock skew ili replay napad.
• WebhookMalformedHeaderError — header nedostaje ili je u pogrešnom formatu.

Politika ponavljanja isporuke

Ako vaš endpoint ne vrati 2xx u roku od 30 sekundi, Platico pokušava ponovo na sledećim intervalima: 5s, 30s, 5min, 30min, 2h, 5h, 10h, 24h. Posle 3 dana odustajemo i obeležavamo dostavu kao failed.

Idempotentno rukovanje

Isti događaj može biti dostavljen više puta (na mrežnoj grešci ili retry-ju). Koristite event.id kao deduplikacioni ključ — sačuvajte ID-ove obrađenih događaja i preskočite duplikate.

Generisanje tajne ključeva

Webhook secret se generiše kada dodajete endpoint u dashboardu. Format: whsec_... Čuvajte ga kao tajnu — ako se ugrozi, rotirajte ga iz Webhook stranice u dashboardu.