Webhook pranešimai

Užprenumeruokite HTTPS galinį tašką sąskaitų faktūrų ir išlaidų įvykiams, tikrinkite HMAC-SHA256 parašą ir tvarkykite pakartotinius siuntimus.

Webhook pranešimai siunčia JSON žinutę į jūsų HTTPS galinį tašką kaskart, kai jūsų versle pasikeičia sąskaita faktūra ar išlaidų dokumentas, nesvarbu, ar pokytis atėjo iš API, programėlės, periodinės sąskaitos ar apmokėjimo. Jie įtraukti į tą patį planą kaip ir API.

Prenumerata

Prenumeratų valdymo API nėra. Programėlėje atidarykite Nustatymai, Integracijos, Webhooks, pridėkite savo galinio taško URL ir pažymėkite norimus įvykius. Programėlė sugeneruoja prenumeratos pasirašymo paslaptį su priešdėliu whsec_. Atskleiskite ją ir išsaugokite kartu su savo galinio taško konfigūracija.

Galinio taško taisyklės:

Privalo būti https://.
Iki 2048 simbolių.

Įvykiai

EVENTinvoice.createdinvoice.created EVENTinvoice.updatedinvoice.updated EVENTinvoice.deletedinvoice.deleted EVENTexpense.createdexpense.created EVENTexpense.updatedexpense.updated EVENTexpense.deletedexpense.deleted

Ką kiekvienas įvykis perduoda ir kada jis siunčiamas:

Įvykis	`data`	Kada
`invoice.created`	visa sąskaita, tokios pačios formos kaip `GET /invoices/{id}`	sukuriama sąskaita, kuri nėra juodraštis
`invoice.updated`	visa sąskaita	bet koks pokytis, įskaitant apmokėjimo būsenos pasikeitimus ir per programėlę gautus apmokėjimus
`invoice.deleted`	`{ "id": "<uuid>" }`	pašalinama sąskaita, kuri nėra juodraštis
`expense.created`	visas išlaidų dokumentas, tokios pačios formos kaip `GET /expenses/{id}`	sukuriamas išlaidų dokumentas
`expense.updated`	visas išlaidų dokumentas	pasikeitė skaičiai arba failas
`expense.deleted`	`{ "id": "<uuid>" }`	pašalinamas išlaidų dokumentas per API arba programėlėje

Sąskaitų juodraščiai įvykių niekada nesukelia. invoice.created išsiunčiamas iš karto, kai sąskaita išsaugoma, dar prieš sugeneruojant jos PDF; apdorojimo funkcijoje atlikta atsisiuntimo užklausa PDF palaukia.

Pristatymas

Kiekvienas pristatymas yra HTTP POST su:

Content-Type: application/json
Signature: <hex HMAC-SHA256 of the raw body, keyed with your whsec_ secret>

Turinys:

{
  "event": "invoice.updated",
  "data": {
    "id": "6f1e9d2a-0b3c-4e5f-8a9b-1c2d3e4f5a6b",
    "invoice_type": "vat_invoice",
    "series": "SF",
    "invoice_number": "007",
    "payment_status": "paid",
    "…": "…"
  }
}

Jūsų galinis taškas privalo atsakyti bet kokia 2xx būsena per 10 sekundžių. Viskas kita, įskaitant laiko limito viršijimą, laikoma nesėkme.

Pakartotiniai siuntimai

Nepavykęs pristatymas kartojamas dar du kartus: po maždaug 10 sekundžių, tada po maždaug 100 sekundžių. Po trijų nesėkmių pranešimas nebesiunčiamas. Todėl pristatymai gali atkeliauti daugiau nei vieną kartą, o intensyviai keičiamo resurso atveju – ir ne iš eilės. Padarykite savo apdorojimo funkciją idempotentišką: dublikatams aptikti naudokite data.id kartu su data.updated_at, o kai svarbi eilės tvarka, gaukite dabartinę būseną per GET /invoices/{id}.

Įvykio identifikatoriaus ar laiko žymos antraštės nėra, programėlėje nėra ir pristatymų žurnalo.

Patikrinkite parašą

Apskaičiuokite HMAC-SHA256 nuo neapdoroto užklausos turinio tiksliai tokio, koks gautas, naudodami prenumeratos paslaptį, ir palyginkite jį pastovaus laiko palyginimu su antrašte Signature.

$secret    = getenv('FSASKAITA_WEBHOOK_SECRET');   // whsec_…
$payload   = file_get_contents('php://input');
$expected  = hash_hmac('sha256', $payload, $secret);
$signature = $_SERVER['HTTP_SIGNATURE'] ?? '';

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

$event = json_decode($payload, true);
// handle $event['event'] and $event['data']
http_response_code(200);

Nuskaitykite turinį kaip neapdorotus baitus prieš bet kokį JSON parsinimą; iš naujo serializuojant išparsintą objektą gali pasikeisti tarpai ar raktų tvarka, ir palyginimas nepavyks.

Atsakykite greitai

Pirmiausia patvirtinkite gavimą 2xx atsakymu, o apdorokite vėliau. Lėtos apdorojimo funkcijos viršija 10 sekundžių limitą, o tai sukelia pakartotinius siuntimus ir dvigubą darbą.

Pakeiskite paslaptį

Ištrinkite prenumeratą ir sukurkite naują; nauja prenumerata gauna naują paslaptį. Jei negalite sau leisti pertrūkio, atnaujinkite galinio taško konfigūraciją prieš ištrindami senąją prenumeratą.