Webhooks

Ειδοποιηθείτε σε πραγματικό χρόνο όταν συμβαίνουν events στον λογαριασμό AgentSend σας — νέα ληφθέντα email, επιβεβαιωμένες παραδόσεις, εντοπισμένα bounces και άλλα.

Επισκόπηση

Αντί να κάνετε polling στο API για νέα μηνύματα, τα webhooks επιτρέπουν στο AgentSend να στέλνει δεδομένα events στον διακομιστή σας τη στιγμή που κάτι συμβαίνει. Εγγράψτε ένα HTTPS endpoint και το AgentSend θα στείλει ένα request POST με JSON payload όποτε ενεργοποιείται ένα subscribed event.

Τα webhooks είναι ο προτεινόμενος τρόπος για να φτιάξετε αντιδραστικούς πράκτορες. Όταν μια απάντηση φτάνει στα εισερχόμενα του πράκτορά σας, η εφαρμογή σας λαμβάνει το πλήρες payload μηνύματος μέσα σε δευτερόλεπτα και μπορεί να ενεργήσει άμεσα.

Δημιουργία Webhook

Εγγράψτε ένα νέο webhook στέλνοντας ένα request POST στο /webhooks. Πρέπει να παρέχετε ένα πεδίο url· όλα τα άλλα πεδία είναι προαιρετικά.

const res = await fetch("https://api.agentsend.io/webhooks", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://myapp.example.com/hooks/agentsend",
    description: "Production inbox events",
    events: ["message.received", "message.bounced"],
  }),
});

const webhook = await res.json();
console.log(webhook.id);     // wh_01j9...
console.log(webhook.secret); // whsec_... store this securely!

Τύποι Events

Εγγραφείτε σε συγκεκριμένα events περνώντας τα αναγνωριστικά τους στον πίνακα events. Αν παραλείψετε τον πίνακα, το AgentSend παραδίδει όλους τους τύπους events στο endpoint σας.

Payload Webhook

Κάθε παράδοση webhook είναι ένα request POST με σώμα Content-Type: application/json. Το payload έχει συνεπή δομή ανεξαρτήτως τύπου event.

{
  "id": "evt_01j9xkq7z8abc",
  "type": "message.received",
  "createdAt": "2026-04-16T10:23:45.000Z",
  "webhookId": "wh_01j9abc123",
  "data": {
    "id": "msg_01j9xkp4n5def",
    "inboxId": "inbox_01j8mq3r2t",
    "threadId": "thr_01j9xkp4m1ghi",
    "fromAddress": "alice@example.com",
    "fromName": "Alice Chen",
    "toAddresses": ["a1b2c3@agentsend.io"],
    "subject": "Re: Your proposal",
    "bodyText": "Looks great, let's move forward.",
    "bodyHtml": "<p>Looks great, let's move forward.</p>",
    "hasAttachments": false,
    "receivedAt": "2026-04-16T10:23:44.812Z"
  }
}

Επαλήθευση Υπογραφών

Κάθε request webhook περιλαμβάνει μια κεφαλίδα X-AgentSend-Signature. Αυτή είναι ένα hash HMAC-SHA256 του raw σώματος request, υπογεγραμμένο με το secret του webhook σας. Πάντα επαληθεύετε αυτή την υπογραφή πριν επεξεργαστείτε μια παράδοση για να προστατευτείτε από πλαστά requests.

import crypto from "node:crypto";

app.post("/hooks/agentsend", express.raw({ type: "application/json" }), (req, res) => {
  const sig       = req.headers["x-agentsend-signature"];
  const secret    = process.env.AGENTSEND_WEBHOOK_SECRET;
  const expected  = crypto
    .createHmac("sha256", secret)
    .update(req.body) // raw Buffer — do NOT parse JSON first
    .digest("hex");

  if (!crypto.timingSafeEqual(
    Buffer.from(sig),
    Buffer.from(expected)
  )) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  // handle event.type …
  res.sendStatus(200);
});

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/hooks/agentsend", methods=["POST"])
def webhook():
    sig      = request.headers.get("X-AgentSend-Signature", "")
    secret   = os.environ["AGENTSEND_WEBHOOK_SECRET"].encode()
    expected = hmac.new(secret, request.data, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(sig, expected):
        abort(401)

    event = request.get_json()
    # handle event["type"] …
    return "", 200

Πολιτική Επαναπροσπάθειας

Το AgentSend θεωρεί μια παράδοση επιτυχημένη όταν το endpoint σας απαντά με οποιοδήποτε HTTP status code 2xx εντός 10 δευτερολέπτων. Αν το request λήξει ή επιστρέψει απάντηση εκτός 2xx, η παράδοση επαναλαμβάνεται με εκθετική καθυστέρηση:

Μετά από 5 αποτυχημένες επαναπροσπάθειες (6 συνολικές προσπάθειες) η παράδοση επισημαίνεται ως failed και δεν γίνονται άλλες προσπάθειες. Μπορείτε να επιθεωρήσετε τις αποτυχημένες παραδόσεις στα logs παράδοσης και να τις επανεκτελέσετε χειροκίνητα από τον πίνακα ελέγχου.

Διαχείριση Webhooks

Το API των webhooks σας επιτρέπει να βλέπετε σε λίστα, να ενημερώνετε και να διαγράφετε τα εγγεγραμμένα endpoints σας.

Λίστα webhooks

Επιστρέφει όλα τα webhooks που είναι εγγεγραμμένα στον λογαριασμό σας.

# GET /webhooks
curl https://api.agentsend.io/webhooks \
  -H "x-api-key: $AGENTSEND_API_KEY"

Ενημέρωση webhook

Αλλάξτε το URL, την περιγραφή ή τους τύπους subscribed events. Μπορείτε επίσης να περιστρέψετε το signing secret περνώντας "rotateSecret": true — η απάντηση θα περιλαμβάνει νέο secret.

# PUT /webhooks/{id}
curl -X PUT https://api.agentsend.io/webhooks/wh_01j9abc123 \
  -H "x-api-key: $AGENTSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": ["message.received", "message.delivered", "message.bounced"]}'

Διαγραφή webhook

Αφαιρεί μόνιμα το webhook. Οι εν ροή παραδόσεις εξακολουθούν να επιχειρούνται πριν τεθεί σε ισχύ η διαγραφή.

# DELETE /webhooks/{id}
curl -X DELETE https://api.agentsend.io/webhooks/wh_01j9abc123 \
  -H "x-api-key: $AGENTSEND_API_KEY"

Παρακολούθηση δραστηριότητας

Λάβετε μια σύνοψη του πρόσφατου όγκου events και των ποσοστών σφαλμάτων για ένα συγκεκριμένο webhook.

# GET /webhooks/activity
curl "https://api.agentsend.io/webhooks/activity?webhookId=wh_01j9abc123" \
  -H "x-api-key: $AGENTSEND_API_KEY"

Logs Παράδοσης

Κάθε προσπάθεια παράδοσης καταγράφεται. Κάντε query στο endpoint logs για να επιθεωρήσετε το πλήρες ιστορικό για ένα webhook, συμπεριλαμβανομένων HTTP response codes, σωμάτων απάντησης και χρόνων.

# Fetch failed deliveries for a webhook
curl "https://api.agentsend.io/webhooks/logs?webhookId=wh_01j9abc123&status=failed" \
  -H "x-api-key: $AGENTSEND_API_KEY"

Κάθε εγγραφή log περιλαμβάνει:

• id — Μοναδικό ID προσπάθειας παράδοσης.
• eventId — Το ID του αρχικού event.
• eventType — π.χ. message.received.
• status — success, failed ή pending.
• httpStatus — Το HTTP response code που επιστράφηκε από το endpoint σας.
• durationMs — Χρόνος round-trip σε χιλιοστά του δευτερολέπτου.
• attempt — Ποια προσπάθεια ήταν αυτή (1 = πρώτη παράδοση).
• createdAt — Χρονοσήμανση της προσπάθειας.