Integration guide

Version 1.0 · 1 October 2026

Receive alarms in your own systems

Dignita sends selected alarms and events as webhooks to your HTTPS endpoint. Each POST request contains one UTF-8 JSON object.

Agree your receiver URL, token and the events you want to receive with Dignita.

HTTP request

POST /dignita/alarms HTTP/1.1
Host: receiver.example.com
Content-Type: application/json
Authorization: Bearer <TOKEN>

Example values. Dignita provides your real URL and token separately.

Connection and endpoint

Connecting

Give Dignita a complete receiver URL, such as https://receiver.example.com/dignita/alarms. Agree which events you want to receive. Dignita provides your token separately. Run a joint connection test with Dignita before activating the integration.

URL requirements

The URL must use HTTPS with a valid certificate, matching hostname and trusted certificate chain. Self-signed certificates are not accepted by default. The URL may contain at most 500 UTF-8 bytes and must not include a username, password or fragment (#).

The endpoint must be publicly reachable. DNS is checked on each delivery and must resolve to allowed public IP addresses. Private, local, reserved and loopback addresses are rejected. The endpoint must respond directly; redirects are not followed.

Authentication

Verify the token

Each request includes Authorization: Bearer <TOKEN>. Verify the token on every request. Reject missing or incorrect tokens, for example with 401, without starting any business action. Store the token in secret configuration and mask it in logs.

Dignita provides your token separately. Check the complete agreed value on every request.

Configuration and token changes

Contact Dignita to change your token. Coordinate the change with your receiver.

Requests have no HMAC signature or separate signature header.

JSON and fields

The message contains the device and notification objects. Position information is in notification.position. The example shows a failed AL-100 test with a position and alcohol value.

Event IDs, times, names and position values may be absent or null. Accept additional JSON fields for future extensions. The table defines the minimum validation requirements; optional fields must not become receiver requirements.

Interpret the event using notification.type. Bind each customer configuration to the agreed endpoint and token.

Message fields

device objectRequired: Device information.
device.id number | stringOptional / may be absent: Device ID. Treat as an identifier.
device.uniqueId stringRequired: Non-empty string, normally an IMEI. Preserve leading zeros.
device.name string | nullOptional / may be absent: Current device name; not a unique identifier. May be null.
notification objectRequired: Event information.
notification.id number | stringOptional / may be absent: Source event ID. Not globally unique; may be absent or null.
notification.type stringRequired: Non-empty, exact, case-sensitive event type.
notification.eventTime Source formatOptional / may be absent: Time of the event. May be absent or null; the format may vary.
notification.serverTime numberRequired: Finite number. Forwarding time as Unix time in milliseconds.
notification.position objectOptional / may be absent: Position information for the event. Position fields may be absent or null.
notification.position.id number | stringOptional / may be absent: Source position ID. May be absent or null.
notification.position.time Source formatOptional / may be absent: Time of the position measurement. May be absent or null; the format may vary.
notification.position.latitude numberOptional / may be absent: Latitude. May be absent or null.
notification.position.longitude numberOptional / may be absent: Longitude. May be absent or null.
notification.additionalInfo objectOptional / may be absent: Only the four AL-100 test types. May be omitted.
notification.additionalInfo.bac numberOptional / may be absent: Numeric alcohol value. Use perMille for the per-mille value.
notification.additionalInfo.perMille numberOptional / may be absent: Per-mille value: bac × 10, at most four decimal places.

AL-100 · failed test

{
  "device": {
    "id": 42,
    "uniqueId": "000123456789012",
    "name": "Exempelenhet"
  },
  "notification": {
    "id": 123,
    "type": "al_test_failed",
    "eventTime": "2026-10-01T08:00:00Z",
    "serverTime": 1790841601000,
    "position": {
      "id": 321,
      "time": "2026-10-01T07:59:59Z",
      "latitude": 59.3293,
      "longitude": 18.0686
    },
    "additionalInfo": {
      "bac": 0.08,
      "perMille": 0.8
    }
  }
}

Example values. Dignita provides your real URL and token separately.

Times, position and alcohol values

Time formats

notification.serverTime is the forwarding time as Unix time in milliseconds. notification.eventTime is the event time, and notification.position.time is the time of the position measurement. Event and position times may be absent or use varying formats. ISO 8601 UTC/Z in the examples is not a format guarantee. Check actual formats in the connection test and preserve the original values. Handle missing or unparseable times, and do not interpret times without a timezone as local time without agreement.

Missing positions

The position may be older than the event; check notification.position.time. When no position is available, all four position fields are null. Individual position fields may also be omitted. A missing position is not the coordinate 0, 0.

Alcohol values and test results

additionalInfo with numeric bac and perMille is supplied only for al_test_passed, al_test_failed, al_retest_passed and al_retest_failed. Use perMille for the per-mille value: perMille = bac × 10, rounded to at most four decimal places. bac 0.08 corresponds to perMille 0.8.

Determine the test result from notification.type, not from a threshold you calculate yourself. An alcohol value of zero provides no separate quality guarantee. Missing additionalInfo means no alcohol value was supplied. This also applies to alco_test_failed.

Alarm without a position

{
  "device": {
    "id": 42,
    "uniqueId": "000123456789012",
    "name": "Exempelenhet"
  },
  "notification": {
    "id": 456,
    "type": "lowBattery",
    "eventTime": "2026-10-01T08:05:00Z",
    "serverTime": 1790841901000,
    "position": {
      "id": null,
      "time": null,
      "latitude": null,
      "longitude": null
    }
  }
}

Example values. Dignita provides your real URL and token separately.

Acknowledgement and delivery errors

Persist before acknowledging

Save the original payload and receipt time in a durable queue or database before returning 204 No Content. Run business logic in the background after responding. A confirmed duplicate already saved may also be acknowledged with 204. If storage fails, return 500 or 503 rather than 2xx.

Accept POST on the agreed path and verify the token first. Then validate JSON: device and notification must be objects, device.uniqueId and notification.type must be non-empty strings, and notification.serverTime a finite number. Invalid JSON or core fields are normally rejected with 400. Do not require position, alcohol values, name, source ID or source time.

Complete the HTTP response

Any HTTP response with status 200–299 counts as successful once the entire response completes, even if your background processing later fails. 204 is recommended; 200 and 202 also work. The response body is not parsed and needs no particular JSON format. Finish the response immediately: an open or streaming response can time out even after 2xx headers.

Timeouts and response size

The entire HTTPS request has a 10-second limit, including connection, TLS, sending and the complete response. DNS has a separate 5-second limit. The response body may be at most 64 KiB (65,536 bytes). Aim to persist and acknowledge within about one second in normal operation. This is not a guarantee of elapsed time from the vehicle event to receipt.

Failed deliveries

Network errors, timeouts and error statuses count as failed deliveries. On timeout, your receiver may already have saved the message even though Dignita did not receive an acknowledgement.

Duplicates and ordering

Requests may arrive concurrently and ordering is not guaranteed. A source event may appear more than once. notification.id is not globally unique and no idempotency-key header is sent.

When enough source fields exist, combine customer configuration, device.uniqueId, notification.id, notification.type and notification.eventTime for duplicate detection. Verify the key against real data. Do not include serverTime; it may change between attempts. If IDs and times are insufficient, preserve events without automatically merging similar messages.

How your HTTP response is handled

2xx: Successful delivery once the complete response ends. 204 recommended.
3xx: Failed delivery. Redirects are not followed.
4xx: Failed delivery, including 400, 401 and 403. No automatic retry.
429: Failed delivery. Retry-After does not trigger a retry.
5xx: Failed delivery. No automatic retry.

AL-100 events

The table shows the exact notification.type values. Only events enabled for your integration are sent. Names are case-sensitive.

The list contains 46 event types. Which occur depends on device capabilities. HS means handset and CB means control box. Use the exact received name, such as al_engine_blocked or al_engine_unblocked.

Save and acknowledge valid messages with new or unknown event types. Flag them for business mapping rather than dropping them.

Search AL-100 events

46 of 46 event types

AL-100 events
Received notification.type	Description
`al_test_passed`	Breath test passed.
`al_test_failed`	Breath test failed.
`al_retest_passed`	Retest passed.
`al_retest_failed`	Retest failed.
`al_hs_connected_cb_after_calibration`	Handset connected after calibration.
`al_memory_full`	Memory full.
`al_handset_disconnected`	Handset disconnected.
`al_handset_reconnected`	Handset reconnected.
`al_invalid_breath_sample`	Invalid breath sample.
`al_out_of_working_temperature_hs`	Handset temperature outside operating range.
`al_out_of_working_temperature_cb`	Control box temperature outside operating range.
`al_main_power_on_cb_turned_on`	Control box power switched on.
`al_low_battery_detected`	Low battery detected.
`al_ignition_turned_off`	Ignition switched off.
`al_ignition_turned_on`	Ignition switched on.
`al_main_power_on_cb_turned_off`	Control box power switched off.
`al_start_of_engine`	Engine start.
`al_starter_relay_opened`	Starter relay opened.
`al_starter_relay_closed`	Starter relay closed.
`al_vehicle_movement_detected`	Vehicle movement detected.
`al_hs_cb_connected_with_new_timestamp`	Handset and control box connected with a new timestamp.
`al_device_error`	Device error.
`al_hs_exchanged`	Handset replaced.
`al_cb_connected_with_computer`	Control box connected to a computer.
`al_serialnumber_not_matched_between_cb_and_hs`	Handset and control box serial numbers do not match.
`al_retest_requested`	Retest requested.
`al_retest_not_delivered`	Requested retest not delivered.
`al_vehicle_movement_detected_without_breath_test`	Vehicle movement without a breath test.
`al_early_service_is_occurred`	Early service occurred.
`al_remainingtime_for_service_due_is_less_than_24_hours`	Less than 24 hours until service is due.
`al_grace_period_started_after_expiry_of_service_date`	Grace period after the service date started.
`al_service_date_including_grace_period_expired`	Service date including grace period expired.
`al_hs_cb_connected_with_new_setting_values`	Handset and control box connected with new settings.
`al_service_date_reset_by_new_timestamp`	Service date reset with a new timestamp.
`al_calibration_done_with_new_timestamp`	Calibration completed with a new timestamp.
`al_serialnumber_of_hs_changed_with_new_pair`	Handset serial number changed on new pairing.
`al_serialnumber_of_cb_changed_with_new_pair`	Control box serial number changed on new pairing.
`al_log_data_deleted`	Log data deleted.
`al_forced_override_activated`	Forced override activated.
`al_forced_override_expired`	Forced override expired.
`al_handset_disconnected_during_engine_run_movement`	Handset disconnected during engine operation and movement.
`al_handset_disconnected_during_engine_run_acc`	Handset disconnected during engine operation with ACC on.
`al_engine_unblocked`	Engine blocking deactivated.
`al_engine_blocked`	Engine blocking activated.
`al_temporary_override_activated`	Temporary override activated.
`al_temporary_override_ended`	Temporary override ended.

Other alarms and models

The alarms you can receive depend on the device model and what is enabled for your integration. Most require tracking to be enabled. Not every device supports every alarm.

For a failed test, AL-100 sends al_test_failed. Some other models send alco_test_failed, without additionalInfo containing alcohol values.

For AL-100, you can receive al_ignition_turned_on when the ignition is switched on and al_ignition_turned_off when it is switched off. These events are sent when enabled for your integration.

Geofence and speed alarms contain the event type and an optional position. JSON does not include a geofence ID, measured speed or threshold.

Other alarms and models
Received notification.type	Description
`deviceOfflinedeviceSleepOn`	Offline or sleep mode.
`deviceOnline`	Online or awake.
`vibration`	Movement or vibration.
`lowBattery`	Low internal battery.
`powerOnpowerOffdeviceChargeOndeviceChargeOff`	External power or charging on/off.
`geofenceEntergeofenceExit`	Geofence entry or exit.
`deviceOverspeed`	Overspeed.
`alco_test_failed`	Failed test on some other models.
`alco_physical_bypass`	Physical bypass on supported models.

Test and go live

Test your receiver

Save the JSON example as alarm-example.json. Set ALARM_ENDPOINT to your test endpoint and ALARM_FORWARDING_TOKEN to the correct token. Never put real tokens in source code or documentation. The command tests your receiver; the expected response is 204 with an empty body.

Joint connection test

A curl test does not replace the joint delivery test from Dignita, including DNS and TLS. Test with the exact URL, a valid certificate, the correct token, a real device linked to the enterprise and at least one intended alarm. Confirm both that you saved the event and that the sender received a complete 2xx response within 10 seconds.

Select only the events you need and check model support and any tracking requirements. A delivery that has already started may use the previous settings.

Check before going live

Valid token and AL-100 test: save the correct type, identifiers and alcohol values, return 2xx.
Without a position: save null, not 0, 0.
Missing ID, name, source time or position fields: accept when core fields are valid.
Incorrect or missing token: reject without business actions.
Invalid JSON or core fields: reject, normally with 400.
Extra JSON fields or unknown type: save, acknowledge and flag for business mapping.
The same source event twice: avoid duplicate business actions when it can be reliably identified.
Concurrent and delayed events: preserve all without assuming an order.
Durable storage failure: do not return a successful 2xx and verify error monitoring.

Test your receiver

curl --request POST "$ALARM_ENDPOINT" \
  --header "Authorization: Bearer $ALARM_FORWARDING_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @alarm-example.json \
  --connect-timeout 3 \
  --max-time 10 \
  --include

Example values. Dignita provides your real URL and token separately.

Operations and troubleshooting

Log receipt time, device.uniqueId, notification.type, source event ID when available and processing results. Mask the token. Monitor storage failures, HTTP errors, response times and background processing errors.

There is no heartbeat. The absence of events does not prove that the connection works. Errors and timeouts do not trigger automatic retries.

When an alarm is missing

Contact Dignita if an alarm is missing. Dignita checks that the device belongs to your integration, which events are enabled and the delivery status. At your receiver, check availability, the token, certificates and durable storage.