Webhooks

Webhooks let DinkyTask send daily plan and submission events to other systems. You configure one webhook endpoint for the family, and DinkyTask automatically sends supported events to that endpoint. The receiver can branch on the top-level event field.

What are they useful for?

triggering IFTTT Webhooks applets
connecting Node-RED, Make, Zapier, or similar automation workflows
calling your own backend, script, or notification service

Where to configure it

Open the Profile page as a parent.
Go to Advanced settings.
Enable the family webhook.
Enter the target URL.
Choose the HTTP method: usually POST.
If needed, enter auth headers as JSON, for example {"Authorization":"Bearer ..."} or {"X-API-Key":"..."}.

The family webhook uses one shared endpoint: when the webhook is enabled, every supported event is delivered to that endpoint.

Events

plan.started — the daily plan started.
plan.completed — all required tasks were approved and the plan succeeded.
plan.failed — the plan did not succeed, for example because a required task failed, was missed, or the plan expired without pending parent reviews.
plan.expired — the plan time window expired while at least one submission was still waiting for parent review; the technical status becomes review_expired.
submission.pending_review — a submission is waiting for parent review.
submission.approved — a submission was approved, either automatically or by a parent.
submission.rejected — a submission was rejected.

HTTP request behavior

The configured method can be POST, PUT, or PATCH.
The payload is sent as JSON.
Each webhook call has a maximum timeout of 10 seconds.
DinkyTask logs each family webhook call, including timestamp, payload, response status, duration, and success/failure, so support can inspect delivery problems later.
Webhook delivery requires an active trial or premium subscription. If access expires, the saved configuration remains in place, but events are not sent again until access returns.

Payload documentation

Every event uses the same base payload structure. Your automation usually checks the event field first and then reads whichever detail it needs.

Root fields

event string
The event name. Possible values: plan.started, plan.completed, plan.failed, plan.expired, submission.pending_review, submission.approved, submission.rejected. plan.expired is sent for review-expired plans (review_expired); ordinary unsuccessful expiry sends plan.failed.
model string
Payload model version, for example plan_bound_v2.
occurred_at string / ISO date
When the event happened according to the server.
status string
The technical plan status, such as active, completed, or failed.
display_status string
Parent/child-facing status. For example, partial means the plan technically failed, but at least one required task was completed.
score number or null
For plan events, the plan score. For submission events, the affected submission score.
automation_key string or null
Optional automation key from the plan. This can be used for routing in Home Assistant, Node-RED, or custom scripts.
child_name string or null
Convenience child name at the payload root.
plan_title string
Convenience plan title at the payload root.
family object
Family data. Currently includes at least id.
child object
Child data: id and name.
plan object
Plan data: id, title, name, automation_key, date, status, start_at, end_at, ordered, score_pct.
summary object
Aggregated result data: required task counts, earned stars/diamonds, score, and task counts.
tasks array
All tasks in the plan with status, order, and reward information.
completed_tasks array
Approved tasks.
failed_tasks array
Failed required tasks.
task object
For submission events, the affected task.
submission object
For submission events, attempt/submission details: id, attempt_type, status, score_pct, submitted_at, and reviewed_at.

`summary` fields

required_completed number
How many required tasks were completed.
required_total number
How many required tasks were in the plan.
stars_earned number
How many ⭐ stars the child earned from approved required tasks.
diamonds_earned number
How many 💎 diamonds the child earned from approved bonus tasks.
score_pct number or null
The calculated plan score percentage when available.
completed_count number
Total number of approved tasks.
failed_required_count number
Number of required tasks in the payload that are not approved.

`tasks[]` fields

id string
Task identifier.
title string
Task title.
type string
Task type, such as quiz, matching, study, photo_proof, video, or habit.
position number
Task position inside the plan.
required boolean
True for required tasks.
bonus boolean
True for bonus/optional tasks.
status string or null
Latest submission status, such as approved, rejected, pending_review, or null if there is no submission yet.
attempt_count number
How many attempts belong to the task.
latest_attempt_status string or null
Latest attempt status, if available.
latest_attempt_no number or null
Latest attempt number, if available.
score number or null
Latest evaluation score when available.
reward_currency string
star for required tasks, diamond for bonus tasks.
reward_points number
Exact reward value for the task.

Full example payload

JSON payload

{
  "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": "Clean up",
      "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": "Math 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 drawing",
      "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": "Clean up",
      "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 drawing",
      "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": "Math 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
    }
  ]
}

Security tip

Only send webhook calls to systems you control or trust. If the receiving service supports secret tokens, unique paths, or API keys, use them.