Εξερχόμενα webhooks: payload και υπογραφή

Ένα εξερχόμενο webhook στέλνει τις ειδοποιήσεις, τις προγραμματισμένες αναφορές, τα δοκιμαστικά μηνύματα και τις περιλήψεις αναφορών του AutoPSEO σε ένα endpoint που διαχειρίζεστε εσείς, ως ένα JSON POST ανά μήνυμα, υπογεγραμμένο με HMAC-SHA256. Χρησιμοποιήστε το για να τροφοδοτήσετε το Zapier, το Make, το n8n, ένα εργαλείο διαχείρισης συμβάντων ή τον δικό σας κώδικα· δεν απαιτείται λογαριασμός Slack ή Teams. Ψάχνετε το webhook που παραδίδει άρθρα στον ιστότοπό σας; Αυτό ανήκει στη μηχανή περιεχομένου: δείτε την παράδοση περιεχομένου.

Προσθήκη webhook

1. Στην ενότητα Outbound webhooks, κάντε κλικ στο New webhook.
2. Δώστε του ένα Name και επικολλήστε το URL του endpoint. Πρέπει να είναι δημόσιο HTTPS: απορρίπτονται το απλό http, το localhost, τα ονόματα που τελειώνουν σε .local ή .internal, οι hosts χωρίς τελεία και οι ιδιωτικές διευθύνσεις IP ή οι διευθύνσεις IP τοπικού συνδέσμου (link-local).
3. Αντιγράψτε το signing secret που εμφανίζεται μετά την αποθήκευση. Εμφανίζεται μόνο αυτή τη φορά.
4. Κάντε κλικ στο Send test για να στείλετε ένα συμβάν test και, στη συνέχεια, συνδέστε στο webhook προγραμματισμένες αναφορές ή ειδοποιήσεις.

Πώς μοιάζει ένα αίτημα webhook

Κάθε μήνυμα είναι ένα POST με τις εξής κεφαλίδες:

Ακολουθεί μια ειδοποίηση πτώσης επισκεψιμότητας για μια ιδιοκτησία τομέα (domain property) από την εκτέλεση των 06:00 UTC της 12ης Οκτωβρίου 2026, μορφοποιημένη για ανάγνωση (στο δίκτυο είναι συμπαγές JSON, και οι τιμές id και site_id είναι επινοημένες):

{
  "id": "9b2e61f04c3a4d7e8f15a0b6c2d39e47",
  "event_type": "traffic_drop",
  "severity": "high",
  "site_id": "4f0c1e9a2b7d4c58",
  "site_url": "sc-domain:example.com",
  "occurred_at": "2026-10-12T06:00:04.183Z",
  "title": "Traffic drop: example.com",
  "text": "Clicks 1,500 vs 2,000 in the previous window (-25.0%).",
  "url": "https://app.autopseo.com/property/sc-domain%3Aexample.com",
  "payload": {
    "fields": [
      { "label": "Metric", "value": "clicks" },
      { "label": "Current", "value": "1,500" },
      { "label": "Baseline", "value": "2,000" },
      { "label": "Window", "value": "7 days (2026-10-05 → 2026-10-11 vs 2026-09-28 → 2026-10-04)" },
      { "label": "Change", "value": "-25.0%" }
    ],
    "table": null,
    "detector": "traffic_drop",
    "window": 7,
    "range": { "start": "2026-10-05", "end": "2026-10-11", "compStart": "2026-09-28", "compEnd": "2026-10-04" },
    "result": {
      "fired": true,
      "metric": "clicks",
      "value": 1500,
      "baseline": 2000,
      "change": -0.25,
      "severity": "high",
      "summary": "Clicks 1,500 vs 2,000 in the previous window (-25.0%)."
    }
  },
  "source": "autopseo"
}

Τα πεδία ανώτατου επιπέδου είναι ίδια για κάθε συμβάν:

Οι λόγοι είναι κλάσματα: μια τιμή change ίση με -0.25 σημαίνει πτώση 25%, και ένα ctr ίσο με 0.034 σημαίνει 3,4%.

Τύποι συμβάντων

Το result επαναλαμβάνει όσα μέτρησε ο ανιχνευτής: fired, metric, value, baseline, change (null όταν δεν υπάρχει στοιχείο σύγκρισης), severity και summary, καθώς και z, το τροποποιημένο z-score, για το anomaly. Τα totals και previous περιέχουν τα clicks, impressions, ctr και position για τα δύο παράθυρα μιας αναφοράς. Τι μετράει κάθε ανιχνευτής περιγράφεται στις Ειδοποιήσεις.

Πώς να επαληθεύσετε την υπογραφή

Η υπογραφή είναι ένα HMAC-SHA256 των ακριβών byte που έστειλε το AutoPSEO, με κλειδί το signing secret του webhook, γραμμένο ως sha256= συν πεζό δεκαεξαδικό. Για να την ελέγξετε:

1. Διαβάστε το ακατέργαστο σώμα του αιτήματος πριν από οποιαδήποτε ανάλυση JSON. Αν το αναλύσετε και το σειριοποιήσετε ξανά, τα byte μπορεί να αλλάξουν.
2. Υπολογίστε το HMAC-SHA256 πάνω σε αυτά τα byte, χρησιμοποιώντας το secret ως κείμενο: τη συμβολοσειρά των 64 χαρακτήρων ακριβώς όπως εμφανίζεται, χωρίς αποκωδικοποίηση από δεκαεξαδικό.
3. Προσθέστε το πρόθεμα sha256= και συγκρίνετε το αποτέλεσμα με την κεφαλίδα X-AutoPSEO-Signature σε σταθερό χρόνο.
4. Απορρίψτε το αίτημα αν διαφέρουν. Διαφορετικά, απαντήστε αμέσως με κατάσταση 2xx και κάντε τη χρονοβόρα εργασία μετά.

Ένας δέκτης για Node.js χωρίς εξαρτήσεις:

import { createServer } from 'node:http';
import { createHmac, timingSafeEqual } from 'node:crypto';

const secret = process.env.AUTOPSEO_WEBHOOK_SECRET;

createServer((req, res) => {
  const chunks = [];
  req.on('data', (chunk) => chunks.push(chunk));
  req.on('end', () => {
    const raw = Buffer.concat(chunks);
    const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(raw).digest('hex'));
    const received = Buffer.from(String(req.headers['x-autopseo-signature'] || ''));
    if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(204).end();
    const event = JSON.parse(raw.toString('utf8'));
    console.log(event.event_type, event.severity, event.site_url);
  });
}).listen(8080);

Ο έλεγχος μήκους γίνεται πρώτος, επειδή η timingSafeEqual του Node προκαλεί εξαίρεση όταν οι δύο buffers έχουν διαφορετικό μήκος.

Κανόνες παράδοσης

• Κάθε μήνυμα γίνεται με μία μόνο προσπάθεια και χρονικό όριο 10 δευτερολέπτων. Οποιαδήποτε απάντηση εκτός από 2xx θεωρείται αποτυχία και καταγράφεται στο Delivery history μαζί με τον κωδικό κατάστασης και την αρχή του σώματος της απάντησής σας.
• Οι ανακατευθύνσεις δεν ακολουθούνται. Μια απάντηση 3xx αποτυγχάνει με σημείωση να χρησιμοποιήσετε το τελικό URL.
• Δεν γίνεται επανάληψη με χρονόμετρο. Μια ειδοποίηση που απέτυχε δεν σημειώνεται ως απεσταλμένη, οπότε ο επόμενος έλεγχός της την αξιολογεί ξανά και την αποστέλλει αν εξακολουθεί να ενεργοποιείται: το επόμενο πρωί για τους περισσότερους ανιχνευτές, την επόμενη ώρα για τα index flips. Μια προγραμματισμένη αναφορά που απέτυχε δεν ξαναστέλνεται στην ίδια περίοδο, γι' αυτό χρησιμοποιήστε το Send now αφού διορθώσετε το endpoint.
• Το id δημιουργείται ανά αίτημα, επομένως προσδιορίζει μια παράδοση και όχι ένα συμβάν. Για να αφαιρέσετε διπλότυπα ειδοποιήσεων, συνδυάστε τα event_type, site_url και την ημερομηνία του occurred_at: ένας κανόνας αποστέλλει το πολύ μία φορά ανά ιδιοκτησία ανά ημέρα UTC, εκτός αν κάποιος εκτελέσει το Test rule.

Το signing secret

Το AutoPSEO εμφανίζει το signing secret μία φορά, όταν αποθηκεύετε το webhook, και η λίστα δεν το εμφανίζει ξανά. Αποθηκεύστε το αμέσως στις ρυθμίσεις του δέκτη σας, μαζί με το endpoint που προστατεύει.

Το ίδιο το URL αποθηκεύεται κρυπτογραφημένο και η λίστα εμφανίζει μόνο τον host και τους τελευταίους χαρακτήρες του. Η διαγραφή ενός webhook διαγράφει επίσης κάθε κανόνα που αποστέλλει σε αυτό. Για μια ευανάγνωστη κάρτα σε ένα κανάλι Teams αντί για JSON, χρησιμοποιήστε το Microsoft Teams.