Webhooks

Webhooks ermöglichen es DinkyTask, Tagesplan- und Abgabeereignisse an andere Systeme zu senden. Du konfigurierst einen Webhook-Endpunkt für die Familie und DinkyTask sendet unterstützte Ereignisse automatisch an diesen Endpunkt. Der Empfänger kann anhand des event-Feldes der obersten Ebene verzweigen.

Wofür sind sie nützlich?

  • IFTTT-Webhook-Applets auslösen
  • Node-RED, Make, Zapier oder ähnliche Automatisierungs-Workflows verbinden
  • dein eigenes Backend, Skript oder deinen eigenen Benachrichtigungsdienst aufrufen

Wo konfigurieren

  1. Öffne die Profil-Seite als Elternteil.
  2. Gehe zu Erweiterte Einstellungen.
  3. Aktiviere den Familien-Webhook.
  4. Gib die Ziel-URL ein.
  5. Wähle die HTTP-Methode: normalerweise POST.
  6. Falls nötig, gib Auth-Header als JSON ein, zum Beispiel {"Authorization":"Bearer ..."} oder {"X-API-Key":"..."}.

Der Familien-Webhook verwendet einen gemeinsamen Endpunkt: Wenn der Webhook aktiviert ist, wird jedes unterstützte Ereignis an diesen Endpunkt geliefert.

Ereignisse

  • plan.started — der Tagesplan hat begonnen.
  • plan.completed — alle Pflichtaufgaben wurden genehmigt und der Plan war erfolgreich.
  • plan.failed — der Plan war nicht erfolgreich, z. B. weil eine Pflichtaufgabe fehlgeschlagen ist, ausgelassen wurde oder der Plan ohne ausstehende elterliche Überprüfungen abgelaufen ist.
  • plan.expired — das Planzeit fenster ist abgelaufen, während mindestens eine Abgabe noch auf elterliche Überprüfung wartete; der technische Status wird review_expired.
  • submission.pending_review — eine Abgabe wartet auf elterliche Überprüfung.
  • submission.approved — eine Abgabe wurde genehmigt, entweder automatisch oder durch einen Elternteil.
  • submission.rejected — eine Abgabe wurde abgelehnt.

HTTP-Anfrageverhalten

  • Die konfigurierte Methode kann POST, PUT oder PATCH sein.
  • Die Nutzlast wird als JSON gesendet.
  • Jeder Webhook-Aufruf hat ein maximales Timeout von 10 Sekunden.
  • DinkyTask protokolliert jeden Familien-Webhook-Aufruf, einschließlich Zeitstempel, Nutzlast, Antwortstatus, Dauer und Erfolg/Misserfolg, damit der Support später Lieferprobleme untersuchen kann.
  • Webhook-Zustellung erfordert ein aktives Test- oder Premium-Abonnement. Wenn der Zugang abläuft, bleibt die gespeicherte Konfiguration vorhanden, aber Ereignisse werden erst wieder gesendet, wenn der Zugang zurückkehrt.

Nutzlast-Dokumentation

Jedes Ereignis verwendet dieselbe Basisnutzlaststruktur. Deine Automatisierung prüft normalerweise zuerst das event-Feld und liest dann die benötigten Details.

Root-Felder

  • event string
    Der Ereignisname. Mögliche Werte: plan.started, plan.completed, plan.failed, plan.expired, submission.pending_review, submission.approved, submission.rejected. plan.expired wird für überprüfungsabgelaufene Pläne gesendet (review_expired); gewöhnliches erfolglosem Ablauf sendet plan.failed.
  • model string
    Nutzlast-Modellversion, zum Beispiel plan_bound_v2.
  • occurred_at string / ISO-Datum
    Wann das Ereignis laut Server stattfand.
  • status string
    Der technische Planstatus, z. B. active, completed oder failed.
  • display_status string
    Eltern-/Kind-seitiger Status. Zum Beispiel bedeutet partial, dass der Plan technisch fehlgeschlagen ist, aber mindestens eine Pflichtaufgabe abgeschlossen wurde.
  • score number oder null
    Für Planereignisse der Planscore. Für Abgabeereignisse der betroffene Abgabe-Score.
  • automation_key string oder null
    Optionaler Automatisierungsschlüssel aus dem Plan. Kann für das Routing in Home Assistant, Node-RED oder eigenen Skripten verwendet werden.
  • child_name string oder null
    Praktischer Kindname im Nutzlast-Root.
  • plan_title string
    Praktischer Plantitel im Nutzlast-Root.
  • family object
    Familiendaten. Enthält derzeit mindestens id.
  • child object
    Kinddaten: id und name.
  • plan object
    Plandaten: id, title, name, automation_key, date, status, start_at, end_at, ordered, score_pct.
  • summary object
    Aggregierte Ergebnisdaten: Pflichtaufgabenzählungen, verdiente Sterne/Diamanten, Score und Aufgabenzählungen.
  • tasks array
    Alle Aufgaben im Plan mit Status, Reihenfolge und Belohnungsinformationen.
  • completed_tasks array
    Genehmigte Aufgaben.
  • failed_tasks array
    Fehlgeschlagene Pflichtaufgaben.
  • task object
    Für Abgabeereignisse die betroffene Aufgabe.
  • submission object
    Für Abgabeereignisse Versuch-/Abgabedetails: id, attempt_type, status, score_pct, submitted_at und reviewed_at.

summary-Felder

  • required_completed number
    Wie viele Pflichtaufgaben abgeschlossen wurden.
  • required_total number
    Wie viele Pflichtaufgaben im Plan waren.
  • stars_earned number
    Wie viele ⭐ Sterne das Kind aus genehmigten Pflichtaufgaben verdient hat.
  • diamonds_earned number
    Wie viele 💎 Diamanten das Kind aus genehmigten Bonusaufgaben verdient hat.
  • score_pct number oder null
    Der berechnete Planscore-Prozentsatz, wenn verfügbar.
  • completed_count number
    Gesamtanzahl genehmigter Aufgaben.
  • failed_required_count number
    Anzahl der Pflichtaufgaben in der Nutzlast, die nicht genehmigt sind.

tasks[]-Felder

  • id string
    Aufgabenkennung.
  • title string
    Aufgabentitel.
  • type string
    Aufgabentyp, z. B. quiz, matching, study, photo_proof, video oder habit.
  • position number
    Position der Aufgabe im Plan.
  • required boolean
    True für Pflichtaufgaben.
  • bonus boolean
    True für Bonus-/optionale Aufgaben.
  • status string oder null
    Letzter Abgabestatus, z. B. approved, rejected, pending_review, oder null wenn noch keine Abgabe vorhanden ist.
  • attempt_count number
    Wie viele Versuche zur Aufgabe gehören.
  • latest_attempt_status string oder null
    Letzter Versuchsstatus, wenn verfügbar.
  • latest_attempt_no number oder null
    Letzte Versuchsnummer, wenn verfügbar.
  • score number oder null
    Letzter Bewertungsscore, wenn verfügbar.
  • reward_currency string
    star für Pflichtaufgaben, diamond für Bonusaufgaben.
  • reward_points number
    Genauer Belohnungswert für die Aufgabe.

Vollständiges Beispiel-Payload

JSON-Nutzlast
{
  "event": "plan.failed",
  "model": "plan_bound_v2",
  "occurred_at": "2026-04-30T18:30:00",
  "status": "failed",
  "display_status": "partial",
  "score": 37.5,
  "automation_key": "homework_done",
  "child_name": "Misi",
  "plan_title": "Misi plan 2026-04-30",
  "family": {
    "id": "80a4cdcd-cd23-431e-81de-ff474f915238"
  },
  "child": {
    "id": "child-user-id",
    "name": "Misi"
  },
  "plan": {
    "id": "plan-id",
    "title": "Misi plan 2026-04-30",
    "name": "Misi plan 2026-04-30",
    "automation_key": "homework_done",
    "date": "2026-04-30",
    "status": "failed",
    "start_at": "2026-04-30T17:00:00",
    "end_at": "2026-04-30T18:30:00",
    "ordered": true,
    "score_pct": 37.5
  },
  "summary": {
    "required_completed": 1,
    "required_total": 2,
    "stars_earned": 3,
    "diamonds_earned": 2,
    "score_pct": 37.5,
    "completed_count": 2,
    "failed_required_count": 1
  },
  "tasks": [
    {
      "id": "task-id-1",
      "title": "Aufräumen",
      "type": "photo_proof",
      "position": 0,
      "required": true,
      "bonus": false,
      "status": "approved",
      "attempt_count": 1,
      "latest_attempt_status": "approved",
      "latest_attempt_no": 1,
      "score": 100,
      "reward_currency": "star",
      "reward_points": 3
    },
    {
      "id": "task-id-2",
      "title": "Mathe-Quiz",
      "type": "quiz",
      "position": 1,
      "required": true,
      "bonus": false,
      "status": "rejected",
      "attempt_count": 1,
      "latest_attempt_status": "rejected",
      "latest_attempt_no": 1,
      "score": 40,
      "reward_currency": "star",
      "reward_points": 5
    },
    {
      "id": "task-id-3",
      "title": "Extra Zeichnen",
      "type": "photo_proof",
      "position": 2,
      "required": false,
      "bonus": true,
      "status": "approved",
      "attempt_count": 1,
      "latest_attempt_status": "approved",
      "latest_attempt_no": 1,
      "score": 100,
      "reward_currency": "diamond",
      "reward_points": 2
    }
  ],
  "completed_tasks": [
    {
      "id": "task-id-1",
      "title": "Aufräumen",
      "type": "photo_proof",
      "position": 0,
      "required": true,
      "bonus": false,
      "status": "approved",
      "attempt_count": 1,
      "latest_attempt_status": "approved",
      "latest_attempt_no": 1,
      "score": 100,
      "reward_currency": "star",
      "reward_points": 3
    },
    {
      "id": "task-id-3",
      "title": "Extra Zeichnen",
      "type": "photo_proof",
      "position": 2,
      "required": false,
      "bonus": true,
      "status": "approved",
      "attempt_count": 1,
      "latest_attempt_status": "approved",
      "latest_attempt_no": 1,
      "score": 100,
      "reward_currency": "diamond",
      "reward_points": 2
    }
  ],
  "failed_tasks": [
    {
      "id": "task-id-2",
      "title": "Mathe-Quiz",
      "type": "quiz",
      "position": 1,
      "required": true,
      "bonus": false,
      "status": "rejected",
      "attempt_count": 1,
      "latest_attempt_status": "rejected",
      "latest_attempt_no": 1,
      "score": 40,
      "reward_currency": "star",
      "reward_points": 5
    }
  ]
}

Sicherheitstipp

Sende Webhook-Aufrufe nur an Systeme, die du kontrollierst oder vertraust. Wenn der empfangende Dienst geheime Token, eindeutige Pfade oder API-Schlüssel unterstützt, verwende sie.