Skip to main content
All CollectionsIntegrations
LOQED web API integration
LOQED web API integration
Updated over a year ago

With some smart home platforms or devices LOQED has no direct integration. If you are an advanced user, you develop your own integration by using the LOQED API. Be sure to read our article "Advanced users: Available APIs" first.

When the door is opened/locked, call an external URL (outgoing webhook)

When the lock’s status is changed (reached this position) (open, unlock, lock), the LOQED backend can call (POST data to) a URL. The URL that you want to call can be added via https://webhooks.loqed.com/. The following JSON data is POSTed to this URL:

  • requested_state (actually, this is the "arrived" state)

    • OPEN

    • DAY_LOCK

    • NIGHT_LOCK

    • UNKNOWN

  • event_type

    • STATE_CHANGED_OPEN (requested_state = OPEN)

    • STATE_CHANGED_LATCH (requested_state = DAY_LOCK)

    • STATE_CHANGED_NIGHT_LOCK (requested_state = NIGHT_LOCK)

    • STATE_CHANGED_UNKNOWN (requested_state = UNKNOWN)

    • MOTOR_STALL (requested_state = UNKNOWN)

  • lock_id

  • key_local_id (null if e.g. manual opening by knob or pressing button)

  • key_name_user (null if e.g. manual opening by knob or pressing button)

  • key_name_admin (null if e.g. manual opening by knob or pressing button)

  • key_account_e-mail (null if e.g. manual opening by knob or pressing button or if PIN of a key that is not bound to an account)

  • key_account_name (null if e.g. manual opening by knob or pressing button or if PIN of a key that is not bound to an account)

Because not all systems support JSON, it is also possible to, for example, call one URL for opening and one URL for locking (obviously, the requested_state variable then is always the same).

Going to a state

You can also request a webhook when the lock is going to a new position (it might not reach the position if the batteries are almost empty, for example).
The following events set the webhook go_to_state attribute with the bolt state.

  • go_to_state

    • OPEN

    • DAY_LOCK

    • NIGHT_LOCK

  • event_type

    • GO_TO_STATE_INSTANTOPEN_OPEN (Touch to Open) (go_to_state = OPEN)

    • GO_TO_STATE_INSTANTOPEN_LATCH (Auto Unlock) (go_to_state = DAY_LOCK)

    • GO_TO_STATE_MANUAL_UNLOCK_BLE_OPEN (go_to_state = OPEN)

    • GO_TO_STATE_MANUAL_LOCK_BLE_LATCH (go_to_state = DAY_LOCK)

    • GO_TO_STATE_MANUAL_LOCK_BLE_NIGHT_LOCK (go_to_state = NIGHT_LOCK)

    • GO_TO_STATE_TWIST_ASSIST_OPEN (go_to_state = OPEN)

    • GO_TO_STATE_TWIST_ASSIST_LATCH (go_to_state = DAY_LOCK)

    • GO_TO_STATE_TWIST_ASSIST_LOCK (go_to_state = NIGHT_LOCK)

    • GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_PIN (go_to_state = OPEN)

    • GO_TO_STATE_MANUAL_UNLOCK_VIA_OUTSIDE_MODULE_BUTTON (go_to_state = OPEN)

    • GO_TO_STATE_TOUCH_TO_LOCK (go_to_state = NIGHT_LOCK)

    • GO_TO_STATE_MANUAL_UNLOCK_REMOTE_OPEN

    • GO_TO_STATE_MANUAL_LOCK_REMOTE_LATCH

    • GO_TO_STATE_MANUAL_LOCK_REMOTE_NIGHT_LOCK

  • lock_id

  • key_local_id (null if e.g. manual opening by knob or pressing button)

  • key_name_user (null if e.g. manual opening by knob or pressing button)

  • key_name_admin (null if e.g. manual opening by knob or pressing button)

  • key_account_e-mail (null if e.g. manual opening by knob or pressing button or if PIN of a key that is not bound to an account)

  • key_account_name (null if e.g. manual opening by knob or pressing button or if PIN of a key that is not bound to an account)

Bluetooth and Wi-Fi strength webhook

Every few hours, or when the lock or bridge is powered, an update of the signal levels can be send. Enable the checkmark to receive this information.

  • ble_strength (percentage - this fluctuates a lot, don't worry if it is low)

  • wifi_strength (percentage)

  • battery_percentage (percentage)

  • lock_id (identification number of your lock)

Lock online webhook

Every few hours, or when the lock or bridge is powered, an update of the signal levels can be send. Enable the checkmark to receive this information.

  • online ("1" is sent as a value)

  • lock_id (identification number of your lock)

Testing

We recommend to use Webhook.site if you want to verify that your smart lock is calling the Webhook URL. You will also be able to see the JSON data there.

Open/lock the door when something happens (incoming webhook)

If you want to control your lock from a third-party service or device, you can do this by way of a HTTPS GET call to a URL of LOQED.

Logging into the LOQED Webhooks platform

image

  • Open the page https://webhooks.loqed.com in your internet browser.

  • Log in using your email address and password that you use for logging into the LOQED app.

    • Attention: Logging into this page will log you out of your LOQED app, you will need to log back into your LOQED app after this.

Creating an API Key

image

On this page you can add outgoing webhooks and create incoming webhooks.

  • Click on "Add new API key".

image
  • Fill in a name for easy identification. This can be anything you'd like, it doesn't have to be the same name as your key.

  • If you have multiple locks, you can select the right lock in the dropdown menu right next to "Select Lock".

  • You can now press "Add API key".

image

You have now created the API key.

Call the API

Currently the API supports the following commands:

  • Open (door opens). An empty JSON object is returned.

  • Latch (unlocked). An empty JSON object is returned.

  • Night lock (locked). An empty JSON object is returned.

  • Status. ATTENTION: please only request the status once per day. If you request the status more than 12 times, you will be blocked for 12 hours. Instead of asking for the status, you should implement a webhook that calls your server, so you get an instant notification as soon as the lock state changes. It returns the following JSON keys:

    • id (lock identification)

    • bridge_online (1 if bridge is online, otherwise 0)

    • lock_online (1 if lock is online, otherwise 0)

    • battery_percentage (-1 if lock is offline, otherwise 0 - 100)

    • battery_type (0 = Alkaline, 1 = NiMH, 2 = Lithium (non-rechargable), 3 = unknown)

    • bolt_state_numeric (0 = unknown, 1 = open, 2 = day_lock, 3 = night_lock)

    • bolt_state (unknown, open, day_lock, night_lock)

    • guest_access_mode (1 if enabled, 0 if disabled)

    • twist_assist (1 if enabled, 0 if disabled)

    • touch_to_connect (1 if Touch to Open 500-meter restriction is removed, 0 otherwise)

Let the LOQED server generate the digital signature

Commands to the smart lock need to be digitally signed. The easiest is to let the LOQED server generate this signature. Simply use the four provided URLs (open, latch, night lock, status) shown on webhooks.loqed.com. If you however prefer to keep your encryption key to yourself and not send it to the LOQED server, you can also generate the digital signature yourself.

Generate the digital signature yourself

At https://app.loqed.com/Backend-API-example/ we provide example code (Javascript and PHP) that shows how the digital signature is created.

Did this answer your question?