Webhook-Referenz

E-Mail-, Slack- oder Discord-Benachrichtigungen? Folge der Benachrichtigungsanleitung.

Der Payload

Jede neue Nachricht löst einen HTTP-POST an deine URL aus mit einem Content-Type: application/json body:

{
  "id": "d8f2e71a20b4",
  "event": "message.created",
  "project": {
    "id": "prj_8f2k1q",
    "name": "acme-site"
  },
  "source": {
    "type": "form",
    "name": "Website contact form"
  },
  "url": "https://mailcontact.app/app/projects/prj_8f2k1q?message=msg_4t9s2e",
  "reply": {
    "url": "https://mailcontact.app/app/projects/prj_8f2k1q?message=msg_4t9s2e",
    "method": "open_conversation"
  },
  "message": {
    "id": "msg_4t9s2e",
    "from": {
      "name": "Ada Lovelace",
      "email": "[email protected]"
    },
    "subject": "Question about pricing",
    "body": "Hi, quick question about the Pro plan...",
    "receivedAt": "2026-07-14T09:30:00.000Z"
  }
}

Felder

• event: message.created für eine eingehende Nachricht oder notification.test für den Testbutton. Bei Testereignissen ist message und source.
• project: das Projekt, dessen Postfach die Nachricht empfangen hat (sein id und name).
• source: woher die Nachricht stammt. type ist "form" (das Formular-Endpunkt) oder "email" (das Projekt-E-Mail-Adresse); name ist die Quellenbezeichnung im Postfach.
• message.from: der Absender mit seinem email (immer vorhanden) und name (kann leer sein, wenn der Absender keinen angegeben hat).
• message.subject: bei Formulareinsendungen optional und daher möglicherweise leer.
• message.receivedAt: Zeitstempel nach ISO 8601, UTC.
• reply.url: öffnet diese Unterhaltung in Mailcontact, wo der Inhaber nach der Anmeldung antworten kann. Der Link allein gewährt keinen Zugriff. Bei Testereignissen ist reply.

Zustellung

• Schnell antworten. Antworte nach Annahme des Payloads sofort mit 2xx und erledige Arbeit asynchron. Zustellungen brechen nach 10 Sekunden ab.
• Mindestens einmal. Eine langsame Antwort oder ein vorübergehender Fehler kann eine Nachricht mehrfach zustellen. Verhindere Duplikate anhand des Payload-Felds id, auch gesendet im Idempotency-Key und X-Mailcontact-Event-Id Headern.
• Vorübergehende Fehler und HTTP 429 werden mit exponentiellen Abständen bis zu fünfmal versucht. Die meisten anderen 4xx-Antworten beenden die Zustellung.
• Nutze einen öffentlichen HTTPS-Endpunkt auf Port 443. Private Netzwerke, Zugangsdaten in URLs und Weiterleitungen werden abgelehnt.

Sicherheit

Payloads sind noch nicht signiert. Wer deine Webhook-URL kennt, kann daher gefälschte Daten senden. Beachte diese Vorsichtsmaßnahmen:

• Verwende einen langen, nicht erratbaren Webhook-Pfad und veröffentliche ihn nirgends.
• Behandle jeden Payload als nicht vertrauenswürdig: Vor jeder Aktion validieren.
• Löse aus unsignierten Webhooks keine zerstörerischen oder unumkehrbaren Aktionen aus. Benachrichtigungen, Protokollierung und Warteschlangen sind okay; Löschen nicht.

Webhook-Signierung ist derzeit nicht verfügbar. Ein empfangener Payload ist kein Absendernachweis.

Webhooks und Benachrichtigungskanäle

Nutze das Benachrichtigungsanleitung für E-Mail-, Slack- und Discord-Benachrichtigungen. Diese Referenz beschreibt das allgemeine Webhook-Format für deinen eigenen Code. Siehe Preise für aktuelle Angebote.