Webhook mechanism

Webhook mechanism

A webhook mechanism is available to avoid querying the API to see if there's new data.

You can setup the URLs where to receive the events in the Nolio API admin.

There are currently 3 webhook channels, each with its own URL:

• Achieved event (webhook_event_real_url) — events in the achieved Calendar (Training, Note, Competition)
• Planned event (webhook_event_planned_url) — events in the planned Calendar (TrainingPlanned, CompetitionPlanned, NotePlanned, QuizPlanned)
• Metrics (webhook_metrics_url) — new or updated metrics

If you leave a URL blank, no webhook will be triggered for that channel.

Achieved event payload

{
  "notif_type": "new_event",
  "object_type": "Training",
  "object_id": 32263,
  "user_id": 10,
  "date_object": "2024-12-02",
  "livemode": true
}

notif_type can be:

• new_event
• updated_event
• deleted_event

object_type can be: Training, Note, Competition.

Planned event payload

Planned events are sent to the webhook_event_planned_url. The payload format is identical to the achieved event one, only the notif_type and object_type values differ.

{
  "notif_type": "new_planned_event",
  "object_type": "TrainingPlanned",
  "object_id": 6688558,
  "user_id": 10,
  "date_object": "2024-12-02",
  "livemode": true
}

notif_type can be:

• new_planned_event
• updated_planned_event
• deleted_planned_event

object_type can be: TrainingPlanned, CompetitionPlanned, NotePlanned, QuizPlanned.

Fan-out: one webhook per concerned athlete

A planned event can target several athletes at once (a group session, or one session planned for many athletes). Nolio sends one webhook per concerned athlete: each delivery carries the user_id of a single athlete, so a planned event targeting 5 athletes produces 5 webhook calls (all with the same object_id, different user_id). Use the (object_id, user_id) couple to deduplicate on your side if needed.

Metrics payload

Metrics are sent to the webhook_metrics_url. The payload carries an extra metric_type field.

{
  "notif_type": "updated_metric",
  "object_type": "Metrics",
  "object_id": 10499,
  "user_id": 100,
  "date_object": "2024-12-03",
  "metric_type": "nombredepas",
  "livemode": true
}

notif_type can be:

• new_metric
• updated_metric
• deleted_metric

date_object on delete

On a delete notification (deleted_event, deleted_planned_event, deleted_metric), the object no longer exists, so the date_object field is omitted from the payload. Delete payloads therefore contain only notif_type, object_type, object_id, user_id, and livemode.

livemode & test deliveries

Every payload carries "livemode":

• true — a real event (all production webhooks).
• false — a test delivery sent from the Send test button on your app's Webhooks page in the portal. Test deliveries also use "object_id": 0 (a sentinel that never resolves). Never treat a livemode: false payload as a real event — ignore it, or use it only to confirm your endpoint receives the request and reads the X-Nolio-Key.

livemode is an additive field (2026-06): it removes nothing, existing integrations can ignore it.

Verifying the request — X-Nolio-Key header

There is a webhook code on the app that is generated by default, and you can change it in the admin.

This code is set up as an HTTP header in the request we will send, to verify it's coming from Nolio.

The code is sent in the X-Nolio-Key header. Use it to discard calls you receive that do not contain the correct code.