Bridge Overview
A Bridge puts your locks online. Your application sends a job to the iglooworks API, the API forwards it to the Bridge over the internet, and the Bridge runs it on the lock over Bluetooth. Results come back to you as webhooks.
Without a Bridge, you can only reach a lock from a phone standing next to it, through the iglooworks app or the Mobile SDK.
How a Job Flows
The POST returns a jobId as soon as the API accepts the job. The lock has not run the command yet. Treat the job as done only when the Job Complete webhook for that jobId arrives.
Lock Jobs
Every Bridge job in the iglooworks API targets a lock through its Bridge: lock, unlock, create or delete a PIN, get battery level, get device status, or get activity logs. Pass departmentId unless the account has a single department. See Lock Jobs.
Before You Start
- Set up the Bridge. Connect it to the internet in the iglooworks app.
- Link each lock to a Bridge. Use the iglooworks app, or the Mobile SDK for in-app linking. The API cannot link locks.
- Register a webhook URL. See Webhook Security.
- Request the right scopes. Each job type has its own scope. See Available Scopes.
Supported Bridges
| Prefix | Bridge | Connectivity |
|---|---|---|
| EB1X | Bridge | 2.4 GHz WiFi |
| EB2X | Bridge 2 | 2.4 GHz WiFi, or Ethernet with the Ethernet adapter accessory |
Each Bridge serves up to 10 locks. Bluetooth range depends on the lock model, so test the Bridge position with each lock you install.
Job Lifecycle
| Stage | What you see |
|---|---|
| Accepted | POST returns 200 with a jobId |
| Rejected | POST returns an error, for example 406 when the Bridge is offline or the lock is not linked |
| Completed | Job Complete webhook with jobStatus 0 (success) |
| Failed | Job Complete webhook with a non-zero jobStatus, for example when the lock is out of range |
| Timed out | No webhook. Poll the job status |
Most jobs complete in under a minute. A job with no result after 2 minutes times out. A timed-out job sends no webhook, so poll the job status to see it.
jobStatus |
Meaning |
|---|---|
0 |
Success |
1 |
Generic error |
2 |
In progress: the Bridge picked up the job and the lock is running it |
Getting Results
Use webhooks. The Job Complete webhook carries the result and any data the job returned, such as the battery level. See Bridge Events and Job Result Payloads.
If a webhook does not arrive, poll Get Bridge Job Status as a fallback. Poll every 10 seconds, and no more often than every 5 seconds.
Events Without a Job
The Bridge also sends webhooks that no job triggered:
- Activity Log Received: lock events the Bridge picks up from locks in range, such as unlocks and PIN entries. The Bridge sends them as close to real time as it can, on a best-effort basis.
- Bridge Connection: the Bridge went online or offline.
See Bridge Events for payloads.
Ordering and Retries
- Send at most 5 jobs per Bridge in any 2-minute window. Above that, jobs are more likely to fail.
- The API does not guarantee job order. If order matters, wait for one job's result before you send the next.
- The API does not retry failed jobs. Create a new job to try again.
jobStatus2means the job is still running. Before you send it again, wait for the result or the 2-minute timeout, or the lock may run the command twice.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
406 Unable to contact bridge as it appears to be offline |
Bridge has no power or internet | Check power and the network. Watch for the Bridge Connection webhook |
406 Lock is not linked to bridge |
Lock is not linked to this Bridge | Link the lock in the iglooworks app |
Job Complete with jobStatus 1 |
Lock out of range, or the command failed on the lock | Move the Bridge closer to the lock, then send a new job |
| No webhook after 2 minutes | Job timed out, or your webhook URL is missing or unreachable | Check your webhook URL, then poll Get Bridge Job Status |
Next Steps
- Lock Jobs: send commands to a lock.
- Bridge Events: handle the webhooks.