Webhookok
Események, HMAC-SHA256 aláírás és ellenőrzése PHP-ban és Node.js-ben, fejlécek, újrapróbálás, teszt, titokcsere és kézbesítési napló.
This article is currently available in Hungarian only.
Webhookkal azonnal értesítjük az alkalmazásodat, ha egy csomag létrejön, státuszt vált, kézbesítik vagy elakad a vámnál, ha lezárod a napot, vagy ha egy reklamáció létrejön vagy módosul. Nem kell folyamatosan lekérdezned (polling): minden változásról HTTP POST-hívást kapsz.
Események
| Esemény | Mikor küldjük |
|---|---|
shipment.created |
Csomag létrejött |
shipment.status_changed |
A csomag státusza megváltozott |
shipment.delivered |
A csomagot kézbesítették |
shipment.failed |
Sikertelen kézbesítés |
shipment.customs_held |
A csomag elakadt a vámnál (a szolgáltatói vámesemény alapján a customs_status mező held lett): hiányzó dokumentum vagy vámfizetés miatt beavatkozás kell |
shipment.revived |
A törölt csomag a szolgáltatónál mégis mozgást mutatott (feladták, úton van, kézbesítették), ezért a szolgáltatói státuszra visszaállt |
manifest.closed |
Lezárult egy nap (napzárás) |
claim.created |
Reklamáció rögzítve (a panelen vagy az API-ból) |
claim.updated |
Reklamáció módosult: állapot, összeg, ügyszám, határidő vagy felelős változott, benyújtották vagy eszkalálták |
Kézbesítéskor és sikertelen kézbesítéskor a shipment.delivered, illetve a shipment.failed mellett a shipment.status_changed eseményt is elküldjük. Ugyanígy a shipment.revived mellett is megy shipment.status_changed.
Melyik végpont kapja meg?
- A csomag eseményeit a csomagot feladó fiók és a fő fiók végpontjaira is elküldjük. Az alfiók így a saját csomagjairól, a fő fiók az összes csomagról értesül.
- A
manifest.closedeseményt a napot lezáró fiók és a fő fiók végpontjai kapják meg. - A
claim.createdés aclaim.updatedeseményt a fő fiók és a csomagot feladó (al)fiók végpontjai kapják meg.
Webhookvégpont létrehozása
- Nyisd meg a Fejlesztőknek oldalt, és a Webhookok résznél kattints az Új végpont gombra.
- Add meg a végpont URL-jét. Csak HTTPS-végpontot adhatsz meg.
- Jelöld ki, mely eseményekre iratkozol fel (alapértelmezés: státuszváltozás).
- Kattints a Hozzáadás gombra.
- Kattints a végpontnál az Új titok gombra, és másold ki az aláíró titkot.
Fontos: Az aláíró titok csak egyszer jelenik meg („Webhook aláíró titok – most másold ki, később nem jelenítjük meg.”). Tárold biztonságosan, például környezeti változóban.
A hívás felépítése
Minden kézbesítés POST-hívás JSON-törzzsel:
{
"id": "01J9Z3K8V4M6Q2R7T5W8X1Y0AB",
"event": "shipment.status_changed",
"created_at": "2026-10-02T13:00:00+02:00",
"data": {
"id": "…",
"status": "in_transit",
"status_label": "…",
"tracking_number": "…"
}
}id: a kézbesítés egyedi azonosítója. Ugyanez azX-Rackoon-Deliveryfejlécben is szerepel.data: a tartalma az eseménytől függ.- Csomageseménynél a csomag ugyanabban a formában, mint a REST API válaszaiban (vámadattal, vámállapottal és vámdokumentum-hivatkozásokkal).
manifest.closedeseménynél a napzárás adatai (szám, szolgáltató, telephely, csomag- és darabszám, felvételi nap, csomagazonosítók).- Reklamációs eseménynél a reklamáció a
GET /claims/{id}alapadataival (belső megjegyzések nélkül).
Fejlécek
| Fejléc | Tartalom |
|---|---|
X-Rackoon-Event |
Az esemény neve |
X-Rackoon-Delivery |
A kézbesítés azonosítója |
X-Rackoon-Timestamp |
Unix-időbélyeg (másodperc) |
X-Rackoon-Signature |
sha256= + HMAC-SHA256 aláírás |
User-Agent |
Rackoon-Webhooks/1.0 |
Az aláírás ellenőrzése
Az aláírás:
sha256=HMAC_SHA256(aláíró titok, X-Rackoon-Timestamp + "." + nyers törzs)A nyers, módosítatlan hívástörzzsel számolj. Ha újrakódolod a JSON-t, megváltozhatnak a bájtok, és az aláírás nem fog egyezni. Az összehasonlításhoz időzítésbiztos függvényt használj.
Tipp: Az időbélyeggel a visszajátszásos támadást is kiszűrheted: utasítsd el azt a hívást, amelynek az időbélyege például 5 percnél régebbi.
PHP
<?php
$secret = getenv('RACKOON_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_RACKOON_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_RACKOON_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);
if (! hash_equals($expected, $signature) || abs(time() - (int) $timestamp) > 300) {
http_response_code(401);
exit;
}
$event = json_decode($body, true);
// Feldolgozás sorban (queue), majd gyors válasz
http_response_code(200);Node.js (Express)
const crypto = require('crypto');
const express = require('express');
const app = express();
app.post(
'/webhooks/rackoon',
express.raw({ type: 'application/json' }),
(req, res) => {
const secret = process.env.RACKOON_WEBHOOK_SECRET;
const timestamp = req.get('X-Rackoon-Timestamp') || '';
const signature = req.get('X-Rackoon-Signature') || '';
const expected =
'sha256=' +
crypto
.createHmac('sha256', secret)
.update(timestamp + '.' + req.body.toString('utf8'))
.digest('hex');
const valid =
signature.length === expected.length &&
crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected),
);
if (!valid || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString('utf8'));
// Feldolgozás sorban (queue), majd gyors válasz
res.sendStatus(200);
},
);Válasz és újrapróbálás
- Sikeresnek a
2xxválasz számít. Minden más státuszkód és a 10 másodpercnél hosszabb válaszidő hibának számít. - Hibánál összesen legfeljebb ötször próbálkozunk, egyre hosszabb szünetekkel: 1 perc, 5 perc, 30 perc, 2 óra.
- Ha egy végpontra egymás után 20 kézbesítés minden próbálkozása sikertelen, kikapcsoljuk a végpontot (Kikapcsolva állapot), és nem kap több eseményt. Egy sikeres kézbesítés nullázza a hibaszámlálót.
Tipp: Válaszolj gyorsan
200-zal, és a feldolgozást végezd háttérfolyamatban. Az esetleges ismételt kézbesítést azid(vagy azX-Rackoon-Delivery) alapján szűrd ki.
Tesztelés
A végpont melletti Teszt gombbal ping eseményt küldhetsz:
{
"id": "…",
"event": "ping",
"created_at": "…",
"data": { "message": "Rackoon webhook teszt" }
}A tesztet sorba állítjuk, az eredménye megjelenik a kézbesítési naplóban. A teszthívást ugyanúgy aláírjuk, mint az éles eseményeket, így az aláírás-ellenőrzést is kipróbálhatod vele.
Titokcsere
Ha a titok kiszivároghatott, vagy rendszeresen cserélnéd, kattints az Új titok gombra. Az új titok azonnal érvényes, a régi pedig megszűnik, ezért a csere után rögtön frissítsd a fogadó oldalon is.
Kézbesítési napló
A Legutóbbi webhook-kézbesítések lista a fiók legutóbbi 25 kézbesítését mutatja:
| Oszlop | Tartalom |
|---|---|
| Esemény | Az esemény neve |
| Végpont | A cél-URL |
| Válasz | A végpont HTTP-státuszkódja |
| Próbálkozás | Eddigi próbálkozások száma |
| Állapot | Kézbesítve, Sikertelen, Sorban vagy Újrapróbálás a következő próbálkozás idejével |
A végpontok listájában az utolsó kézbesítés ideje is látszik. A nem használt végpontot a Törlés gombbal törölheted.
Kezelés a REST API-ból
A webhook-végpontokat webhooks:manage jogosultságú API-kulccsal is kezelheted, mindig a kulcs fiókjában. Az aláíró titkot a létrehozás (POST /webhooks) és a titokcsere (POST /webhooks/{id}/rotate-secret) válaszában kapod meg, egyetlen alkalommal.
# Választható események
curl https://api.elkuldom.hu/v1/webhooks/events \
-H "Authorization: Bearer $RACKOON_API_KEY"
# Végpont létrehozása (a válasz data.secret mezője az aláíró titok)
curl -X POST https://api.elkuldom.hu/v1/webhooks \
-H "Authorization: Bearer $RACKOON_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://webshop.hu/webhooks/rackoon","events":["shipment.status_changed","shipment.customs_held"]}'
# Tesztesemény és kézbesítési napló (csak a sikertelenek)
curl -X POST https://api.elkuldom.hu/v1/webhooks/12/test -H "Authorization: Bearer $RACKOON_API_KEY"
curl "https://api.elkuldom.hu/v1/webhooks/deliveries?webhook_id=12&failed=1" -H "Authorization: Bearer $RACKOON_API_KEY"
# Titokcsere és törlés
curl -X POST https://api.elkuldom.hu/v1/webhooks/12/rotate-secret -H "Authorization: Bearer $RACKOON_API_KEY"
curl -X DELETE https://api.elkuldom.hu/v1/webhooks/12 -H "Authorization: Bearer $RACKOON_API_KEY"