Webhooks

Zustellung von Ereignissen ans Kundenportal — geplant. Heute holt das Portal Job-Status (GET /v1/send-jobs/{id}), Mail-Status (GET /v1/messages/{id}) und Sperren (GET /v1/suppressions) ab; das reicht für Builder, Versand und Auswertung. Die Zustellung kommt später als Zusatz auf dieselben Daten: job.completed, message.bounced, suppression.changed. Die Registrierung einer URL ist schon möglich, die Zustellung noch nicht.

Bald verfügbar

POST

/v1/webhooks

Bald verfügbar

Registriert eine HTTPS-URL, an die später Ereignisse gepusht werden (job.completed, message.bounced, suppression.changed). Bis die Zustellung gebaut ist, holt das Portal Job-, Mail- und Sperrstatus ab. Die Antwort enthält EINMALIG ein signing_secret — damit jede Zustellung über den Header X-NewsletterKit-Signature verifiziert werden kann. Scope full.

Body-Parameter

Name	Typ	Pflicht	Beschreibung
url	string (URL)	erforderlich	HTTPS-Endpunkt der Kundenplattform (http wird abgelehnt). `z. B. https://kunde.de/hooks/newsletterkit`
events	string[]	optional	Abonnierte Ereignisse: job.completed \| message.bounced \| suppression.changed. Default: ["job.completed"]. `z. B. ["job.completed","message.bounced"]`

Request · Next.js

const res = await fetch(`https://api.newsletterkit.ventureon.io/v1/webhooks`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEWSLETTERKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      url: "https://kunde.de/hooks/newsletterkit",
      events: ["job.completed","message.bounced"],
    }),
});
const data = await res.json();

Response 200

{
  "data": {
    "id": "wh_5d33…",
    "url": "https://kunde.de/hooks/newsletterkit",
    "events": ["job.completed", "message.bounced"],
    "active": true,
    "signing_secret": "whsec_… (nur hier einmalig)"
  },
  "request_id": "…"
}

signing_secret wird nur in dieser Antwort zurückgegeben und ist danach nicht mehr abrufbar — sicher speichern. Zustellungen tragen die Header X-NewsletterKit-Event, X-NewsletterKit-Delivery (Dedup) und X-NewsletterKit-Signature: t=<unix>,v1=<hmac>. Verifikation: HMAC-SHA256 über "<t>.<roher Body>" mit dem signing_secret bilden und mit v1 vergleichen.

POST

/api/postmark/webhook

Eingehender Endpunkt für Postmark-Events (Delivery, Open, Click, Bounce, SpamComplaint). Dieser Endpunkt ist KEIN API-Key-Endpunkt — er wird ausschließlich von Postmark aufgerufen und über eine Signatur/ein geheimes Token verifiziert. Aus den Events werden die aggregierten email_stats fortgeschrieben (PII-frei); Bounces/Complaints landen als gehashte Adresse im Suppression-Netz.

Body-Parameter

Name	Typ	Pflicht	Beschreibung
RecordType	string	erforderlich	Postmark-Event-Typ: Delivery \| Open \| Click \| Bounce \| SpamComplaint. `z. B. Delivery`
MessageID	string	optional	Postmark-Message-ID zur Zuordnung zum Versand. `z. B. pm_abc123`
Metadata	object	optional	Beim Versand mitgegebene Metadaten (message_id, customer_id, send_job_id) für die Zuordnung. `z. B. {"composition_id":"c0a8…"}`

Request · Next.js

const res = await fetch(`https://api.newsletterkit.ventureon.io/api/postmark/webhook`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NEWSLETTERKIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({
      RecordType: "Delivery",
      MessageID: "pm_abc123",
      Metadata: {"composition_id":"c0a8…"},
    }),
});
const data = await res.json();

Response 200

{ "ok": true }

Kein Bearer-API-Key: Authentizität wird über die Postmark-Signatur bzw. ein geheimes URL-Token sichergestellt. Wird vom Kunden nicht direkt aufgerufen — hier nur zur Vollständigkeit dokumentiert.