Dokumentationsmenü

Webhooks & Ereignisse

Konto-Webhooks senden, was in Ihrem ganzen Konto passiert, in Echtzeit an eine URL Ihrer Wahl: einen neuen Lead, einen gebuchten Termin, einen Deal, der die Phase wechselt. Die Integrationen für Zapier und n8n nutzen sie im Hintergrund, und Sie können sie auch auf Ihren eigenen Endpunkt richten. Wenn Sie nur Zapier nutzen, müssen Sie keinen Webhook selbst anlegen: Die Karte Zapier auf der Seite Entwickler startet einen Zap aus einer Vorlage, und der Zap richtet seinen Webhook selbst ein.

Sie ergänzen den Projekt-Webhook auf der Antwortseite einer einzelnen E-Mail, der weiter wie bisher funktioniert. Ein Projekt-Webhook deckt die Interaktionen einer E-Mail ab. Ein Konto-Webhook deckt alle E-Mails ab, dazu die Ereignisse unten, und wird genauso signiert.

Einen Webhook hinzufügen

  1. Gehen Sie im Dashboard zu Entwickler und suchen Sie die Karte Webhooks.
  2. Geben Sie die Endpunkt-URL ein (eine öffentliche https://-URL) und wählen Sie die gewünschten Ereignisse.
  3. Klicken Sie auf Webhook hinzufügen und kopieren Sie das Signatur-Secret. Es wird nur dieses eine Mal angezeigt.

Jeder Webhook zeigt, wie er angelegt wurde (Dashboard, API, Zapier oder n8n), seinen Status und seine letzte Zustellung. Test senden schickt ein Beispiel des gewählten Ereignisses, mit "test": true in data. Löschen entfernt den Webhook. Ein Konto kann bis zu 50 haben.

Nur der Kontoinhaber kann Webhooks hinzufügen oder löschen, und unter Umständen wird er vorher um eine erneute Anmeldung gebeten.

Ereignisse

EreignisWird ausgelöst, wenn
interaction.receivedEin Empfänger mit einer E-Mail interagiert: Umfragestimme, Bewertung, Quiz-Antwort, verfolgter Klick, Kauf und so weiter. Deduplizierte Wiederholungen lösen nichts aus.
form.submittedEin Formular in einer E-Mail abgesendet wird (source: "email-form") oder ein Anmeldeformular (source: "signup-form").
contact.createdEin Kontakt einer Liste hinzugefügt wird.
contact.updatedSich die Felder eines Kontakts ändern. Das Speichern identischer Daten löst nichts aus.
lead.hotDer Engagement-Score eines Kontakts Ihren Schwellenwert für heiße Leads nach oben überschreitet.
lead.newEin neuer Lead über ein Anmeldeformular oder ein Formular in einer E-Mail eintrifft.
booking.createdEin Termin gebucht wird.
booking.cancelledEine Buchung storniert wird, mit cancelledBy. Eine Verschiebung löst keines der beiden Buchungsereignisse aus.
deal.createdEin Deal angelegt wird, egal wo: Board, Automatikregel, Journey, Angebot oder API.
deal.stage_changedEin Deal die Phase wechselt, gewonnen und verloren eingeschlossen.
purchase.completedEin Empfänger über einen Checkout in der E-Mail bezahlt.
journey.completedEin Kontakt das Ende einer Journey erreicht. Wer vorzeitig aussteigt, zählt nicht.
experiment.decidedJemand die Entscheidung eines Experiments festhält: Gewinner, kein Unterschied oder nicht eindeutig.
experiment.completedDie abschließenden Ergebnisse eines Experiments vorliegen: Die Auswertung über sein ganzes Beobachtungsfenster ist gelaufen.
response.completedEin Empfänger hat jeden Block beantwortet, den eine E-Mail zählt, zum Beispiel jede Frage einer Umfrage. Einmal pro Empfänger und E-Mail.
review.submittedEin Empfänger hat über einen Block „Bewertungsanfrage“ eine Bewertung abgeschickt. Wird einmal pro Bewertung ausgelöst.

Die Kontaktereignisse werden bei Importen, Anmeldeformularen, der API, Synchronisationen und KI-Connectoren ausgelöst. Ein einzelner Schreibvorgang mit mehr als 500 Kontakten (etwa ein großer CSV-Import) löst keine aus, damit ein Import nicht Tausende Workflows startet. Ein im Kontaktraster hinzugefügter Kontakt, eingetippt oder aus einer CSV übernommen, löst contact.created aus. Bearbeitungen bestehender Kontakte dort lösen kein contact.updated aus, ebenso wenig Journey-Schritte Feld aktualisieren oder gespeicherte Antworten.

lead.hot und lead.new werden unabhängig von den Schaltern und Grenzen Ihrer Lead-Benachrichtigungen ausgelöst: Das Abonnement ist die Zustimmung.

Beide Experiment-Ereignisse enthalten {experiment}, in derselben Form, die die Experiment-API liefert: seine Varianten, das neueste result der Auswertung, die festgehaltene decision mit der evidence, die ihr die Auswertung gegeben hat, und eine resultsUrl. experiment.completed wird pro Experiment einmal ausgelöst, auch wenn die Entscheidung bei einem sequenziellen Test früher festgehalten wurde. Bei einem Experiment in einer Journey nennt ein Gewinner einen Pfad: decision.pathIndex.

response.completed enthält die E-Mail (projectId, projectName), den recipient-Schlüssel und seinen contact, sendId und variant, wenn ein Versand sie verschickt hat (sonst null), die gezählten blockIds und in answers die Antwort jedes Blocks, denselben Wert, den interaction.received als event.value enthält, dazu firstAnsweredAt und completedAt. Eine E-Mail zählt jede Umfrage, Bewertung, jedes Quiz, RSVP und Formular, das der Empfänger sieht, außer der Bereich Antworten im Studio wählt weniger, und unter zwei löst es nie aus. Eine später geänderte Antwort löst es nicht erneut aus, und eine Ansicht ohne Empfänger (eine Vorschau, ein allgemeiner Link) wird nie vollständig.

review.submitted enthält die E-Mail (projectId, projectName), die blockId, in subject was bewertet wurde (kind, id, title), die rating, title und body, den gewählten displayName, verifiedPurchase, contact und recipient sowie submittedAt.

Payload

Jede Zustellung ist ein JSON-POST mit demselben Umschlag:

{
  "id": "evt_8c1f…",
  "type": "deal.stage_changed",
  "createdAt": 1790000000000,
  "data": {
    "deal": {
      "id": "deal_abc123",
      "title": "Annual plan",
      "value": 1200,
      "currency": "USD",
      "pipelineId": "owner_default",
      "stageId": "proposal-sent",
      "stage": "Proposal sent",
      "status": "open",
      "source": "manual",
      "listId": "list_abc123",
      "rowId": "3f6c1b0e2d…",
      "email": "[email protected]"
    },
    "fromStageId": "meeting-booked"
  }
}

id ist bei jeder Zustellung desselben Ereignisses gleich und wird auch im Header X-MailInApp-Idempotency-Key mitgeschickt, sodass Sie eine bereits verarbeitete erneute Zustellung gefahrlos verwerfen können. createdAt ist in Epoch-Millisekunden.

Um das data jedes Ereignistyps zu sehen, rufen Sie GET /api/v1/events/sample auf oder verwenden Sie Test senden.

Die Signatur prüfen

Zustellungen tragen die Header X-MailInApp-Timestamp und X-MailInApp-Signature, berechnet genau wie bei einem Projekt-Webhook. Prüfen Sie sie mit Ihrem Signatur-Secret gegen den rohen Body und weisen Sie Zeitstempel zurück, die älter als ein paar Minuten sind. Die Dokumentation des Projekt-Webhooks enthält eine fertige Node.js-Funktion.

Wiederholungen

Ihr Endpunkt hat 5 Sekunden Zeit, mit einem 2xx zu antworten. Alles andere (Zeitüberschreitung, Fehlerstatus, Weiterleitung) ist ein Fehlschlag, und die Zustellung wird automatisch mit wachsenden Abständen über mehrere Stunden wiederholt, mit demselben Body und demselben Idempotenzschlüssel, an die aktuelle URL des Webhooks. Antworten Sie schnell und erledigen Sie langsame Arbeit danach.

  • Antwortet Ihr Endpunkt mit 410 Gone, wird der Webhook deaktiviert. So melden sich REST-Hooks-Clients ab.
  • Das Widerrufen eines API-Schlüssels deaktiviert die damit angelegten Webhooks.
  • Das Löschen eines Webhooks beendet seine ausstehenden Wiederholungen.

Über die API abonnieren

Zapier, n8n und Ihr eigener Code können Webhooks mit einem API-Schlüssel verwalten (Authorization: Bearer mia_live_…):

curl https://mailinapp.com/api/v1/webhooks \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/mailinapp", "events": ["lead.hot", "booking.created"]}'

Die Antwort 201 enthält die id des Abonnements und sein secret, das jede Zustellung signiert. Bewahren Sie es auf: Es wird nicht noch einmal geliefert. GET /api/v1/webhooks listet Ihre Abonnements, und DELETE /api/v1/webhooks/{id} entfernt eines. Ein einziger unbekannter Ereignisname lässt die ganze Anfrage scheitern. Diese Routen erlauben 30 Anfragen pro Minute und Schlüssel.

Der vollständige Vertrag steht in der OpenAPI-Spezifikation.

Experimentergebnisse abrufen

Mit einem API-Schlüssel kann Ihr Code Ihre Experimente lesen, etwa um die Zahlen abzurufen, sobald experiment.completed eintrifft:

  • GET /api/v1/experiments listet sie auf, die neuesten zuerst. Filtern Sie mit status, kind (send oder journey), projectId oder journeyId.
  • GET /api/v1/experiments/{id} liefert eines.
  • GET /api/v1/experiments/{id}/results liefert das Experiment mit seinem vollständigen Bericht: dieselben Zahlen wie der JSON-Export der Ergebnisseite, nur aggregierte Werte.

Diese Routen lesen nur. Sperren, Starten, Entscheiden und das Ausrollen eines Gewinners bleiben im Dashboard. Sie erlauben 60 Anfragen pro Minute und Schlüssel. Experimentergebnisse lesen erklärt, was die Zahlen bedeuten.