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ó.

8 Min. LesezeitAktualisiert: 03.11.2026

Dieser Artikel ist derzeit nur auf Ungarisch verfügbar.

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.closed eseményt a napot lezáró fiók és a fő fiók végpontjai kapják meg.
  • A claim.created és a claim.updated eseményt a fő fiók és a csomagot feladó (al)fiók végpontjai kapják meg.

Webhookvégpont létrehozása

  1. Nyisd meg a Fejlesztőknek oldalt, és a Webhookok résznél kattints az Új végpont gombra.
  2. Add meg a végpont URL-jét. Csak HTTPS-végpontot adhatsz meg.
  3. Jelöld ki, mely eseményekre iratkozol fel (alapértelmezés: státuszváltozás).
  4. Kattints a Hozzáadás gombra.
  5. 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:

JSON
{
    "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 az X-Rackoon-Delivery fejlé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.closed esemé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
<?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)

JavaScript
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 2xx vá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 az id (vagy az X-Rackoon-Delivery) alapján szűrd ki.

Tesztelés

A végpont melletti Teszt gombbal ping eseményt küldhetsz:

JSON
{
    "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.

cURL
# 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"

Kapcsolódó cikkek