Webhooks

Εγγράψτε HTTP endpoints για να λαμβάνετε ειδοποιήσεις events σε πραγματικό χρόνο. Επιθεωρήστε logs παράδοσης και παρακολουθήστε δραστηριότητα στις συνδρομές webhook σας.

ⓘ

Όλα τα requests απαιτούν την κεφαλίδα x-api-key. Το base URL για κάθε endpoint είναι https://api.agentsend.io.

Το Αντικείμενο Webhook

Κάθε endpoint που επιστρέφει webhook επιστρέφει αυτή τη δομή. Το πεδίο secret περιλαμβάνεται μόνο στην απάντηση του POST /webhooks — αποθηκεύστε το με ασφάλεια, καθώς δεν μπορεί να ανακτηθεί ξανά.

json

{
  "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "url": "https://your-app.com/webhooks/agentsend",
  "description": "Production inbound handler",
  "events": ["message.received", "message.bounced"],
  "isActive": true,
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T10:00:00.000Z"
}

Πεδίο	Τύπος	Περιγραφή
`id`	string (uuid)	Μοναδικό αναγνωριστικό webhook.
`url`	string (uri)	Το HTTPS endpoint στο οποίο το AgentSend παραδίδει events.
`description`	string \| null	Προαιρετική αναγνώσιμη από άνθρωπο ετικέτα για το webhook.
`events`	string[] \| null	Πίνακας subscribed τύπων events. `null` ή κενός πίνακας σημαίνει ότι παραδίδονται όλα τα events.
`isActive`	boolean	Αν το webhook λαμβάνει αυτή τη στιγμή events.
`createdAt`	string (ISO 8601)	Πότε δημιουργήθηκε το webhook.
`updatedAt`	string (ISO 8601)	Πότε ενημερώθηκε τελευταία το webhook.

Δημιουργία Webhook

POST /webhooks

Register a new webhook endpoint. Returns 201 Created with the Webhook object plus a secret field. Use the secret to verify webhook signatures — it is only returned once and cannot be retrieved later.

Σώμα Request

Παράμετρος	Τύπος	Περιγραφή
`url` απαιτείται	string (uri)	Το HTTPS URL στο οποίο το AgentSend θα κάνει POST τα events. Πρέπει να είναι έγκυρο URI που ξεκινά με `https://`.
`description`	string	Αναγνώσιμη από άνθρωπο ετικέτα για την αναγνώριση αυτού του webhook στον πίνακα ελέγχου και τα logs.
`events`	string[]	Λίστα τύπων events για εγγραφή. Παραλείψτε ή περάστε κενό πίνακα για λήψη όλων των events. Έγκυρες τιμές: `domain.verified`, `message.received`, `message.sent`, `message.delivered`, `message.bounced`, `message.complained`.

Παράδειγμα Request

javascript

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://your-app.com/webhooks/agentsend",
    description: "Production inbound handler",
    events: ["message.received", "message.bounced"],
  }),
});

const webhook = await res.json();
console.log(webhook.secret); // Save this — it won't be shown again

Απάντηση — 201 Created

json

{
  "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "url": "https://your-app.com/webhooks/agentsend",
  "description": "Production inbound handler",
  "events": ["message.received", "message.bounced"],
  "isActive": true,
  "secret": "whsec_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T10:00:00.000Z"
}

⚠

Το secret επιστρέφεται μόνο κατά τη δημιουργία. Αποθηκεύστε το αμέσως σε ασφαλή μεταβλητή περιβάλλοντος — δεν μπορείτε να το ανακτήσετε ξανά μέσω του API.

Λίστα Webhooks

GET /webhooks

Επιστρέφει όλα τα εγγεγραμμένα webhooks για τον λογαριασμό σας. Τα secrets δεν περιλαμβάνονται ποτέ σε απαντήσεις λίστας ή λήψης.

Παράδειγμα Request

javascript

const res = await fetch("https://api.agentsend.io/webhooks", {
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});

const { data } = await res.json();
console.log(`${data.length} webhooks registered`);

Απάντηση — 200 OK

json

{
  "data": [
    {
      "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
      "url": "https://your-app.com/webhooks/agentsend",
      "description": "Production inbound handler",
      "events": ["message.received", "message.bounced"],
      "isActive": true,
      "createdAt": "2026-04-16T10:00:00.000Z",
      "updatedAt": "2026-04-16T10:00:00.000Z"
    }
  ]
}

Λήψη Καταλόγου Events

GET /webhooks/catalog

Επιστρέφει την πλήρη λίστα τύπων events στους οποίους μπορούν να εγγραφούν τα webhooks σας, συμπεριλαμβανομένων ονομάτων και περιγραφών. Χρησιμοποιήστε αυτό για τη συμπλήρωση UIs event-picker ή την επικύρωση ονομάτων events κατά το runtime.

Παράδειγμα Request

javascript

const res = await fetch("https://api.agentsend.io/webhooks/catalog", {
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});

const { data } = await res.json();
data.forEach(e => console.log(e.name, e.description));

Απάντηση — 200 OK

json

{
  "data": [
    {
      "name": "domain.verified",
      "description": "Fired when a custom domain passes DNS verification."
    },
    {
      "name": "message.received",
      "description": "Fired when an inbound email arrives in an inbox."
    },
    {
      "name": "message.sent",
      "description": "Fired when an outbound message is accepted by the recipient mail server."
    },
    {
      "name": "message.delivered",
      "description": "Fired when delivery to the recipient mailbox is confirmed."
    },
    {
      "name": "message.bounced",
      "description": "Fired when a message hard-bounces."
    },
    {
      "name": "message.complained",
      "description": "Fired when a recipient marks the message as spam."
    }
  ]
}

Λίστα Logs Παράδοσης

GET /webhooks/logs

Επιστρέφει λίστα με μεμονωμένες προσπάθειες παράδοσης webhook, ταξινομημένες με πιο πρόσφατες πρώτες. Χρησιμοποιήστε αυτό για debug αποτυχημένων παραδόσεων, επιθεώρηση payloads και αναθεώρηση response codes από το endpoint σας.

Παράμετροι Query

Παράμετρος	Τύπος	Περιγραφή
`webhookId`	string (uuid)	Φιλτράρετε logs σε συγκεκριμένο webhook. Αν παραλειφθεί, επιστρέφονται logs για όλα τα webhooks.
`status`	enum	Φιλτράρισμα ανά αποτέλεσμα παράδοσης. Μία από τις: `success` ή `failed`.
`event`	string	Φιλτράρισμα ανά τύπο event, π.χ. `message.received`.
`limit`	integer	Μέγιστος αριθμός εγγραφών log προς επιστροφή. Προεπιλογή `20`.
`hours`	integer	Παράθυρο αναδρομής σε ώρες. Προεπιλογή `168` (7 ημέρες).

Παράδειγμα Request

javascript

const params = new URLSearchParams({
  webhookId: "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  status: "failed",
  limit: "50",
  hours: "24",
});

const res = await fetch(
  `https://api.agentsend.io/webhooks/logs?${params}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data } = await res.json();
data.forEach(log => console.log(log.event, log.responseStatus));

Απάντηση — 200 OK

json

{
  "data": [
    {
      "id": "whl_01hx9k2v3w4x5y6z7a8b9c0d",
      "webhookId": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
      "event": "message.received",
      "status": "failed",
      "responseStatus": 503,
      "durationMs": 4821,
      "attempts": 3,
      "createdAt": "2026-04-16T11:05:00.000Z"
    }
  ]
}

Λήψη Δραστηριότητας

GET /webhooks/activity

Επιστρέφει συγκεντρωτική δραστηριότητα παράδοσης (αριθμοί επιτυχιών και αποτυχιών στον χρόνο) για ένα ή όλα τα webhooks. Χρήσιμο για rendering διαγραμμάτων σε πίνακα παρακολούθησης.

Παράμετροι Query

Παράμετρος	Τύπος	Περιγραφή
`webhookId`	string (uuid)	Περιορίστε τη δραστηριότητα σε συγκεκριμένο webhook. Αν παραλειφθεί, επιστρέφεται δραστηριότητα για όλα τα webhooks.
`hours`	integer	Παράθυρο αναδρομής σε ώρες. Προεπιλογή `6`.

Παράδειγμα Request

javascript

const res = await fetch(
  "https://api.agentsend.io/webhooks/activity?webhookId=wh_01hx9k2v3w4x5y6z7a8b9c0d&hours=24",
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const activity = await res.json();
console.log(activity.successCount, activity.failureCount);

Απάντηση — 200 OK

json

{
  "webhookId": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "hours": 24,
  "successCount": 142,
  "failureCount": 3,
  "buckets": [
    { "timestamp": "2026-04-15T11:00:00.000Z", "success": 18, "failure": 0 },
    { "timestamp": "2026-04-15T12:00:00.000Z", "success": 24, "failure": 1 }
  ]
}

Λήψη Webhook

GET /webhooks/{id}

Ανακτήστε μεμονωμένο webhook με το ID του. Το secret δεν επιστρέφεται ποτέ μετά τη δημιουργία.

Παράμετροι Διαδρομής

Παράμετρος	Τύπος	Περιγραφή
`id` απαιτείται	string (uuid)	Το ID του webhook προς ανάκτηση.

Παράδειγμα Request

javascript

const res = await fetch(
  `https://api.agentsend.io/webhooks/${webhookId}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const webhook = await res.json();
console.log(webhook.isActive, webhook.events);

Απάντηση — 200 OK

Επιστρέφει μεμονωμένο αντικείμενο Webhook (χωρίς secret).

json

{
  "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "url": "https://your-app.com/webhooks/agentsend",
  "description": "Production inbound handler",
  "events": ["message.received", "message.bounced"],
  "isActive": true,
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T10:00:00.000Z"
}

Ενημέρωση Webhook

PUT /webhooks/{id}

Ενημερώστε μία ή περισσότερες ιδιότητες υπάρχοντος webhook. Όλα τα πεδία σώματος είναι προαιρετικά — θα αλλάξουν μόνο τα πεδία που παρέχετε. Χρησιμοποιήστε isActive: false για να παύσετε παραδόσεις χωρίς να διαγράψετε το webhook.

Παράμετροι Διαδρομής

Παράμετρος	Τύπος	Περιγραφή
`id` απαιτείται	string (uuid)	Το ID του webhook προς ενημέρωση.

Σώμα Request

Παράμετρος	Τύπος	Περιγραφή
`url`	string (uri)	Νέο URL προορισμού. Πρέπει να ξεκινά με `https://`.
`description`	string	Ενημερωμένη αναγνώσιμη από άνθρωπο ετικέτα.
`events`	string[]	Αντικαθιστά την πλήρη λίστα subscribed τύπων events. Περάστε κενό πίνακα για εγγραφή σε όλα τα events.
`isActive`	boolean	Ορίστε σε `false` για παύση παραδόσεων ή `true` για συνέχιση.

Παράδειγμα Request

javascript

const res = await fetch(
  `https://api.agentsend.io/webhooks/${webhookId}`,
  {
    method: "PUT",
    headers: {
      "x-api-key": process.env.AGENTSEND_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      events: ["message.received", "message.delivered", "message.bounced"],
      isActive: true,
    }),
  }
);

const updated = await res.json();
console.log(updated.events); // updated event list

Απάντηση — 200 OK

Επιστρέφει το ενημερωμένο αντικείμενο Webhook.

json

{
  "id": "wh_01hx9k2v3w4x5y6z7a8b9c0d",
  "url": "https://your-app.com/webhooks/agentsend",
  "description": "Production inbound handler",
  "events": ["message.received", "message.delivered", "message.bounced"],
  "isActive": true,
  "createdAt": "2026-04-16T10:00:00.000Z",
  "updatedAt": "2026-04-16T12:34:00.000Z"
}

Διαγραφή Webhook

DELETE /webhooks/{id}

Διαγράφει μόνιμα ένα webhook. Όλες οι μελλοντικές παραδόσεις events σε αυτό το endpoint θα σταματήσουν άμεσα. Τα logs παράδοσης που σχετίζονται με το webhook διατηρούνται για λόγους ελέγχου.

⚠

Αυτή η ενέργεια είναι μη αναστρέψιμη. Αν θέλετε να σταματήσετε προσωρινά τις παραδόσεις, χρησιμοποιήστε PUT /webhooks/{id} με isActive: false αντί αυτού.

Παράμετροι Διαδρομής

Παράμετρος	Τύπος	Περιγραφή
`id` απαιτείται	string (uuid)	Το ID του webhook προς διαγραφή.

Παράδειγμα Request

javascript

await fetch(
  `https://api.agentsend.io/webhooks/${webhookId}`,
  {
    method: "DELETE",
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
); // 204 No Content

Απάντηση — 204 No Content

Επιστρέφει κενό σώμα σε επιτυχία.

Τύποι Events

Οι εξής τύποι events μπορούν να περαστούν στο events κατά τη δημιουργία ή ενημέρωση webhook. Παραλείψτε το πεδίο events εντελώς (ή περάστε κενό πίνακα) για να λάβετε όλα τα events.

Event	Περιγραφή
`domain.verified`	Ένας προσαρμοσμένος τομέας πέρασε την επαλήθευση DNS και είναι έτοιμος για χρήση.
`message.received`	Ένα εισερχόμενο email έφτασε σε ένα από τα inboxes σας.
`message.sent`	Ένα εξερχόμενο μήνυμα έγινε αποδεκτό από τον διακομιστή mail του παραλήπτη.
`message.delivered`	Η παράδοση στο mailbox του παραλήπτη επιβεβαιώθηκε (όπου υποστηρίζεται).
`message.bounced`	Ελήφθη hard bounce — η διεύθυνση δεν υπάρχει ή απέρριψε την παράδοση.
`message.complained`	Ο παραλήπτης επισήμανε το μήνυμα ως spam.

💡

Για να δείτε τις πλήρεις δομές payload για κάθε τύπο event, επισκεφθείτε τον εννοιολογικό οδηγό Webhooks.

← Προηγούμενο API: Νήματα Επόμενο → API: Τομείς