WebHook Dokumentum
Ügyféloldali leírás a webhook integráció használatához.
Tartalom
Mi ez?
A WebHook funkció lehetővé teszi, hogy a Monitorozás.hu egy esemény bekövetkezésekor automatikusan HTTP POST kérést küldjön a megadott külső URL-re.
Ilyen esemény lehet például: device riasztás, blacklist állapotváltozás, értesítés sikeres vagy hibás kiküldése, illetve teszt esemény.
Biztonság
Minden webhook rekordhoz saját secret tartozik. A küldött kérés aláírása HMAC-SHA256 algoritmussal történik.
Fontos: a fogadó oldalon mindig ellenőrizd a secret alapján képzett aláírást.
Ne csak az IP címre vagy a User-Agent mezőre hagyatkozz.
Ajánlott ellenőrzések:
- Bearer token vagy saját titkos azonosító ellenőrzése
- X-Webhook-Signature fejléc ellenőrzése
- JSON payload validálása
- Naplózás és hibaválasz kezelése
HTTP headerek
A Monitorozás.hu a webhook hívás során jellemzően az alábbi headereket küldi:
Content-Type: application/json
User-Agent: Monitorozas.hu-Webhook/1.0
X-Webhook-Event: device_alert_raised
X-Webhook-Signature: sha256=ALÁÍRÁS
Authorization: Bearer SAJAT_SECRET_VAGY_TOKEN
Megjegyzés:
- X-Webhook-Event az esemény típusát tartalmazza
- X-Webhook-Signature a payload HMAC-SHA256 aláírása
- az Authorization fejléc opcionális védelemként használható a fogadó oldalon
Eseménytípusok
| Esemény kulcs | Jelentés |
|---|---|
device_alert_raised |
Device riasztás létrejött |
blacklist_listed |
Blacklistre került |
blacklist_cleared |
Blacklist helyreállás |
notification_sent |
Értesítés sikeresen kiküldve |
notification_failed |
Értesítés végleg sikertelen |
test.ping |
Teszt ping |
A webhook oldalon checkboxokkal kiválasztható, hogy egy adott URL mely eseményeket,
illetve mely végpontok és blacklist monitorok eseményeit kapja meg.
Payload minták
1. test.ping
{
"event": "test.ping",
"occurred_at": "2026-04-03T16:10:18+00:00",
"webhook": {
"id": 1,
"name": "tesztelek",
"url": "https://example.com/webhook.php"
},
"data": {
"message": "hello from Monitorozás.hu",
"user_id": 1
}
}
2. device_alert_raised
{
"event": "device_alert_raised",
"occurred_at": "2026-04-03T16:20:01+00:00",
"alert": {
"severity": "critical",
"kind": "public_https_down",
"message": "Teszt device down"
},
"device": {
"id": 999,
"target_info": "https://teszt.monitorozas.hu"
},
"result": {
"transport_ok": 0,
"check_ok": 0,
"http_code": null,
"ttfb_ms": 0,
"error_text": "manual test"
}
}
3. blacklist_listed
{
"event": "blacklist_listed",
"occurred_at": "2026-04-03T16:20:02+00:00",
"monitor": {
"id": 777,
"target_type": "domain",
"target_value": "mail.teszt.hu"
},
"status": {
"previous": "OK",
"current": "LISTED"
},
"listed_rows": [
{
"list": "Spamhaus ZEN",
"answer": "127.0.0.2"
}
]
}
4. blacklist_cleared
{
"event": "blacklist_cleared",
"occurred_at": "2026-04-03T16:20:03+00:00",
"monitor": {
"id": 777,
"target_type": "domain",
"target_value": "mail.teszt.hu"
},
"status": {
"previous": "LISTED",
"current": "OK"
},
"listed_rows": []
}
5. notification_sent
{
"event": "notification_sent",
"occurred_at": "2026-04-03T16:20:04+00:00",
"notification": {
"id": 555,
"channel": "email",
"recipient": "teszt@pelda.hu",
"subject": "Teszt értesítés",
"status": "sent"
}
}
6. notification_failed
{
"event": "notification_failed",
"occurred_at": "2026-04-03T16:20:05+00:00",
"notification": {
"id": 556,
"channel": "sms",
"recipient": "+36300000000",
"subject": "Teszt hibás értesítés",
"status": "failed",
"last_error": "manual fail"
}
}
PHP fogadó példa
Egyszerű PHP webhook fogadó példa secret és aláírás ellenőrzéssel:
<?php
declare(strict_types=1);
header('Content-Type: application/json; charset=UTF-8');
$secret = 'IDE_A_WEBHOOK_SECRET';
$rawBody = file_get_contents('php://input') ?: '';
$event = $_SERVER['HTTP_X_WEBHOOK_EVENT'] ?? '';
$sigHdr = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$authHdr = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
if ($rawBody === '') {
http_response_code(400);
echo json_encode(['success' => false, 'error' => 'empty_body']);
exit;
}
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
if (!hash_equals($expected, $sigHdr)) {
http_response_code(401);
echo json_encode(['success' => false, 'error' => 'invalid_signature']);
exit;
}
$data = json_decode($rawBody, true);
if (!is_array($data)) {
http_response_code(400);
echo json_encode(['success' => false, 'error' => 'invalid_json']);
exit;
}
// Itt saját logika:
file_put_contents(
__DIR__ . '/webhook.log',
'[' . gmdate('Y-m-d H:i:s') . " UTC] event={$event} payload=" . $rawBody . PHP_EOL,
FILE_APPEND
);
echo json_encode([
'success' => true,
'received' => $event
], JSON_UNESCAPED_UNICODE);
Node.js fogadó példa
const express = require('express');
const crypto = require('crypto');
const app = express();
const secret = 'IDE_A_WEBHOOK_SECRET';
app.use(express.json({
verify: (req, res, buf) => {
req.rawBody = buf.toString('utf8');
}
}));
app.post('/webhook', (req, res) => {
const event = req.header('X-Webhook-Event') || '';
const sig = req.header('X-Webhook-Signature') || '';
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(req.rawBody || '', 'utf8')
.digest('hex');
if (sig !== expected) {
return res.status(401).json({ success: false, error: 'invalid_signature' });
}
console.log('Webhook event:', event, req.body);
return res.json({
success: true,
received: event
});
});
app.listen(3000, () => {
console.log('Webhook listener running on :3000');
});
curl teszt példa
Egyszerű kézi teszt fogadó oldal ellenőrzéséhez:
curl -X POST https://example.com/webhook.php \
-H "Authorization: Bearer SAJAT_SECRET" \
-H "Content-Type: application/json" \
-d '{
"event": "test.ping",
"data": {
"msg": "hello from curl"
}
}'
Elvárt válasz
A fogadó oldalnak siker esetén érdemes HTTP 200 választ adnia, például:
{
"success": true,
"received": "device_alert_raised"
}
Ha a fogadó oldal nem 2xx státusszal válaszol, akkor a küldés sikertelennek minősül, és a rendszer retry logikát alkalmazhat.
Hibakezelés és ajánlások
- Mindig naplózd a nyers payloadot vagy annak kivonatát
- Ellenőrizd a signature-t minden kérésnél
- A fogadó oldalon legyen timeout és hibakezelés
- Idempotens feldolgozás javasolt, hogy ugyanaz az esemény többször se okozzon problémát
- Ha belső rendszerbe továbbítod, használj queue-t
A webhook history és a delivery státuszok a Monitorozás.hu felületén a Webhookok oldalon követhetők.