Webhooks

Webhooks are the primary way for you to be notified about events that happen in the August system.

All types of webhooks (locks, doorbells, keypads, and users) work with the same pattern:

You set up an internet-facing service which can receive an HTTP POST.
You register for webhooks when a user links their account to August using OAuth.
Time passes.
An event happens. For example, a lock is unlocked or a wifi bridge goes offline.
August sends one webhook to the URL you registered.

When the user unlinks their account from August, delete the webhook registration.

Required

Use of webhooks is required for your integration to pass the certification.

Registering for webhooks#

Create a webhook registration to start receiving webhooks for a lock, doorbell, or user.

Locks#

Use this endpoint to register for webhooks about lock related events. If the lock has a keypad, you will also receive webhooks for keypad related events.

Each lock can have one webhook registered per user. If you call this endpoint again for the same user, then the existing webhook registration will be overwritten.

The following example creates a webhook registration for events of type operation and battery. When an event happens, the API sends a webhook to your url.

POST /webhook/:lockID

{
  "url": "https://your.webhook.endpoint/",
  "method": "POST",
  "clientID": "your_client_id",
  "header": "x-my-header",
  "token": "my_secret_value",
  "notificationTypes": [
    "operation",
    "battery"
  ]
}

Note the token and header parameters:

header: The name of a header that the API will send in the webhook.
token: The value of that header that the API will send in the webhook.

The HTTP request from the above example would look something like this.

POST https://your.webhook.endpoint/

content-type: application/json
x-my-header: my_secret_value

{
  // The body of the request.
}

This header should have meaning to your API -- it is a way to pass parameters to your webhook.

Note

The API does not send this header in webhooks for the PIN management or remote operate endpoints.

Doorbells#

Use this endpoint to register for webhooks about doorbell related events.

Each doorbell can have one webhook registered per user. If you call this endpoint again for the same user, then the existing webhook registration will be overwritten.

POST /webhook/doorbell/:doorbellID

{
  "url": "https://your.webhook.endpoint/",
  "method": "POST",
  "clientID": "your_client_id",
  "header": "x-my-header",
  "token": "my_secret_value",
  "notificationTypes": [
    "motiondetected",
    "videoavailable",
    "buttonpush"
  ]
}

Users#

Use this endpoint to register for webhooks about user related events.

Each user can have one webhook registered. If you call this endpoint again for the same user, then the existing webhook registration will be overwritten.

POST /webhook/user

{
  "url": "https://your.webhook.endpoint/",
  "method": "POST",
  "clientID": "your_client_id",
  "header": "x-my-header",
  "token": "my_secret_value",
  "notificationTypes": [
    "lockmembership",
    "lifecycle"
  ]
}

Deleting webhook registrations#

Delete a webhook registration to stop receiving webhooks.

Locks#

Use this endpoint to delete a lock webhook registration.

DELETE /webhook/:lockID/:clientID

Doorbells#

Use this endpoint to delete a doorbell webhook registration.

DELETE /webhook/doorbell/:doorbellID/:clientID

Users#

Use this endpoint to delete a user webhook registration.

DELETE /webhook/user/:clientID

Webhook event types#

Locks#

operation:
- The lock was locked, unlocked, or its status was checked by anyone.
- The door was opened or closed for locks with a DoorSense™ sensor.
configuration:
- The name of the lock changed.
- A keypad PIN was managed (created, updated, or deleted)
battery: The batteries are low in the lock or its keypad.
systemstatus: The lock went offline or came offline (i.e. reachable remotely)
accessmgmt:
- A user was added or removed from the lock.
- A user's access level was changed on the lock. (e.g. from guest to owner).
- A user's access schedule was changed on the lock. (e.g. from always to temporary)

Doorbells#

motiondetected: The doorbell detected motion.
videoavailable: A doorbell video is available.
buttonpush: Someone rang the doorbell.

Users#

lockmembership: The user was added to or removed from a lock.
lifecycle: The user deleted their account.

Retries#

If a webhook fails, August retries it for up to 24 hours with an exponential back off. Failed webhooks are those that return a response code that is not 200-299, 400, 401, or 403.

This is the retry schedule.

Retry #	Delay
1	30 seconds
2	60 seconds
3	2 minutes
4	4 minutes
5	8 minutes
6	16 minutes
7	32 minutes
8	1 hour
9	8 hours
10	24 hours

Checking signatures#

Every webhook has a signature in the X-August-Signature header. This signature allows you to verify that the webhook was sent by August, not by a third party.

Preventing replay attacks#

A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, August includes a timestamp in the X-August-Signature header. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the webhook. We recommend a default tolerance of 5 minutes.

How to check a signature#

August generates signatures using a hash-based message authentication code (HMAC) with SHA-256, signed with your API key.

Step 1. Extract timestamp and signature from the header Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v corresponds to the signature.

Step 2. Create the payload string The payload_string is created by concatenating the following:

timestamp as a string
the character .
The stringified JSON payload (the request body).

Step 3. Generate the expected signature Compute an HMAC with the SHA-256 hash function. Use your API key as a signing secret and the payload_string as the message.

Step 4. Compare the expected and actual signature Compare the signature in the header to the expected signature. Compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

Example lock webhooks#

For the following webhook examples, Timestamp is when the event happened. Say the user unlocked via the keypad. The lock saves the timestamp then.

At some point in the future, the log for that event is sent to our system through the wifi bridge. We then set timeStamp to when we send the webhook.

Lock or unlock#

The lock was locked or unlocked.

with August app or API#

The lock was operated with the August app or the API.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "operation",
  "Event": "unlock",
  "Device": "lock",
  "User": {
    "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
    "FirstName": "Example",
    "LastName": "User",
    "PhoneNo": "+16505551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    }
  }
}

Event	Meaning
`unlock`	The lock was unlocked.
`lock`	The lock was locked.

with Keypad#

The lock was operated via the keypad.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "operation",
  "Event": "unlock",
  "Device": "keypad",
  "User": {
    "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
    "FirstName": "Example",
    "LastName": "User",
    "PhoneNo": "+16505551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    }
  }
}

Event	Meaning
`unlock`	The lock was unlocked.
`lock`	The lock was locked.

manually#

Someone turned the lock manually.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "timeStamp": 1662762147868,
  "EventID": "192fda30-9062-4301-822e-12829578ac67",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "operation",
  "Event": "unlock",
  "Device": "lock",
  "User": {
    "UserID": "manualunlock"
  },
  "Timestamp": 1662762142000
}

Event	Meaning
`unlock`	The lock was unlocked.
`lock`	The lock was locked.

UserID	Meaning
`manualunlock`	The lock was unlocked.
`manuallock`	The lock was locked.

One Touch Lock#

Body

{
  "timeStamp": 1721846117326,
  "EventID": "8c29fd48-bb14-43b9-8f76-91cc53e8364f",
  "LockID": "14E34D351982449181E093E6DC43EFCB",
  "EventType": "operation",
  "Event": "onetouchlock",
  "Device": "keypad",
  "User": {
    "UserID": "onetouchlock",
    "FirstName": "One Touch",
    "LastName": "Lock",
    "PhoneNo": "n/a",
    "Email": "n/a",
    "imageInfo": "n/a"
  },
  "Timestamp": 1721846116000
}

Door opened or closed#

The door was opened or closed (for locks with a DoorSense™ sensor).

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "operation",
  "Event": "open",
  "Device": "lock",
  "User": {
    "UserID": "DoorStateChanged"
  }
}

Event	Meaning
`closed`	The door was closed.
`open`	The door was opened.
`ajar`	The door was opened very slightly.

Lock status#

The Event tells you the state of the lock which the status check returned.

So operation webhooks will now send you two EventType: "operation" and "status". The "operation" fires as soon as the actual event happens. The "status" fires whenever anyone calls /remoteoperate/status and notifies all listeners on that lock of the current status.

That way you can reduce the number of times you call status yourself. You always know the latest state of the lock, at least as well as any other listeners do.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "status",
  "Event": "lock",
  "Device": "lock",
  "User": {
    "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
    "FirstName": "Example",
    "LastName": "User",
    "PhoneNo": "+16505551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    }
  }
}

Event	Meaning
`unlock`	The lock is unlocked.
`lock`	The lock is locked.

Lock name change#

The user changed the name of the lock.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "configuration",
  "Event": "lock_name_changed",
  "Lock": {
    "Name": "new lock name"
  },
  "User": {
    "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
    "FirstName": "Example",
    "LastName": "User",
    "PhoneNo": "+16505551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    }
  }
}

Lock battery warning#

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "EventType": "system",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "Event": "lock_battery_alert",
  "warningLevel": "lock_state_battery_warning_2week",
  "userID": "4337d8c6-0fda-4068-989c-aba166ae6b9d"
}

userID: The ID of the user who registered for the webhook.

warningLevel	Meaning
`lock_state_battery_warning_none`	The lock's batteries are high.
`lock_state_battery_warning_2week`	The lock's batteries should last about 2 weeks more.
`lock_state_battery_warning_1week`	The lock's batteries should last about 1 week more.
`lock_state_battery_warning_2day`	The lock's batteries should last about 2 days more.

Lock privacy mode#

The lock entered or exited privacy mode. Privacy mode disables the keypad so that all keypad PIN codes, and the master code, will not unlock the lock until it exits privacy mode.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "EventType": "configuration",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "Event": "privacy_mode",
  "Value": true,
}

Value	Meaning
true	The lock is now in privacy mode.
false	The lock is no longer in privacy mode.

Lock vacation mode#

A user put the lock into vacation mode or normal mode in the Yale Access mobile app. Vacation mode disables the keypad so that entry codes will not unlock the lock until it exits vacation mode.

This webhook only fires for locks with integrated keypads like the Yale Assure 2. Locks that use detached keypads, like the Yale Smart Keypad, fire the keypad enabled webhook.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "EventType": "configuration",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "Event": "vacation_mode",
  "Value": true,
}

Value	Meaning
true	The lock is now in vacation mode.
false	The lock is no longer in vacation mode.

Lock clock is wrong#

The lock sent a log to the August API that has a timestamp that is in the future or too far in the past. Most likely the batteries ran out at some point in the past and the lock's real time clock is now wrong. Connect to the lock with the August app or the August SDK to correct it's clock.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json

x-my-header: my_secret_value

Body

{
  "EventType": "systemstatus",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "Event": "lock_log_timestamp_drifted",
  "warningLevel": "lock_state_battery_warning_2week",
  "Timestamp": 1678750917002,
  "TimestampDrifted": 2487412339000
}

TimestampDrifted: The timestamp from the lock, which is either in the future or too far in the past.
Timestamp: The timestamp of when August sent the webhook.

Keypad enabled or disabled#

A user enabled or disabled the keypad in the Yale Access mobile app.

Keypads that are disabled cannot operate their lock.
PIN codes cannot be loaded onto disabled keypads through the API.

This webhook only fires for locks with detached keypads like the Yale Smart Keypad. Locks with integrated keypads, like the Yale Assure 2, fire the vacation mode webhook.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "EventType": "configuration",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "Event": "keypad_enabled",
  "Value": false,
}

Value	Meaning
true	The keypad is enabled.
false	The keypad is disabled.

Keypad PIN managed#

A keypad PIN was added, deleted, enabled, disabled or had its schedule modified. These webhooks apply to PINs that were managed with the August/Yale mobile app, utilizing the SDK, or using the HTTP API.

When you call the PIN management endpoint to manage PINs for your own users, you can send additional webhooks.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "configuration",
  "Event": "keypad_pin_managed",
  "Lock": {
    "Name": "Front Door"
  },
  "Pin": {
    "state": "load",
    "action": "commit",
    "pin": "123456",
    "accessType": "recurring",
    "accessTimes": "STARTSEC=36000;ENDSEC=73800",
    "accessRecurrence": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH"
  },
  "PinUser": {
    "UserID": "2d82e357-c2ec-4c37-9127-ad867b1bde7f",
    "FirstName": "Another",
    "LastName": "User",
    "PhoneNo": "+14085551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    },
    "PartnerUserID": "n/a or some-partnerUserID-from-a-pin-command"
  },
  "User": {
    "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
    "FirstName": "Example",
    "LastName": "User",
    "PhoneNo": "+16505551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    }
  },
  "Timestamp": 1701300012207
}

User is the lock owner who added the PIN to the lock.
PinUser is the user who the PIN is assigned to.

state	Meaning
`load`	A PIN was added to the lock.
`disable`	A PIN was disabled.
`enable`	A PIN was enabled.
`delete`	A PIN was deleted.
`update`	A PIN was updated (code and/or schedule)

Keypad master PIN managed#

The master PIN was changed on the lock. This applies to locks with built-in keypads, like the Yale Assure Lock 2.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "timeStamp": 1675813513629,
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "configuration",
  "Event": "keypad_pin_managed",
  "EventID": "912efb36-5b24-473f-ab27-f4c9b057deb0",
  "Lock": {
    "Name": "Front Door"
  },
  "Pin": {},
  "PinUser": {
    "UserID": "masterpin",
    "FirstName": "Master",
    "LastName": "PIN",
    "PhoneNo": "n/a",
    "Email": "n/a",
    "imageInfo": "n/a"
  },
  "User": {
    "UserID": "masterpin",
    "FirstName": "Master",
    "LastName": "PIN",
    "PhoneNo": "n/a",
    "Email": "n/a",
    "imageInfo": "n/a"
  },
  "Timestamp": 1675813513574
}

Keypad battery warning#

The battery webhook fires when the August servers learn that the batteries on a device are running low enough that the owner should be notified.

Keypads and locks can both run low on batteries.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "EventType": "battery",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "Event": "keypad_battery_critical",
  "DeviceType": "keypad",
  "DeviceSerialNumber": "K1G0000001"
}

Event	Meaning
`keypad_battery_none`	The keypad's batteries are high.
`keypad_battery_warning`	The keypad's batteries are running low.
`keypad_battery_critical`	The keypad's batteries need replacing immediately or the it may not work.

Wifi bridge went offline or online#

The Connect Wi-Fi Bridge associated with a lock either went offline or came online.

It takes about 5 minutes for the August servers to decide that a bridge is offline, so this webhook will not fire immediately when the bridge goes offline. However, the server will send a webhook as soon as it sees the bridge come back online.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "EventType": "systemstatus",
  "LockID": ["1234567890ABCDEF1234567890ABCDEF"],
  "Event": "online"
}

Event	Meaning
`online`	The bridge went online.
`offline`	The bridge came offline.

User added to the lock#

A user was added to the lock.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "authorization",
  "Event": "lock_user_add",
  "Lock": {
    "Name": "Front Door"
  },
  "User": {
    "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
    "FirstName": "Example",
    "LastName": "User",
    "PhoneNo": "+16505551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    }
  }
}

User removed from the lock#

A user was removed from the lock.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "authorization",
  "Event": "lock_user_remove",
  "Lock": {
    "Name": "Front Door"
  },
  "User": {
    "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
    "FirstName": "Example",
    "LastName": "User",
    "PhoneNo": "+16505551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    }
  }
}

User access level changed on lock#

A user's access level was changed on the lock. For example, from guest to owner.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "timeStamp": 1663970396958,
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "authorization",
  "Event": "lock_usertype_changed",
  "Lock": {
    "Name": "Front Door"
  },
  "User": {
    "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
    "FirstName": "Example",
    "LastName": "User",
    "PhoneNo": "+16505551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    },
    "UserType": "user"
  },
  "EventID": "44387d09-25e8-4529-96bc-bcb9088e5045",
  "Timestamp": 1663970396948
}

UserType	Meaning
`user`	The user is now a guest.
`superuser`	The user is now an owner.

User access schedule changed on lock#

A user's access schedule was changed on the lock. For example, from always to temporary.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "timeStamp": 1663970396958,
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventType": "authorization",
  "Event": "lock_accesstype_changed",
  "Lock": {
    "Name": "Front Door"
  },
  "User": {
    "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
    "FirstName": "Example",
    "LastName": "User",
    "PhoneNo": "+16505551212",
    "Email": "user@example.com",
    "imageInfo": {
      "original": {
        "width": 640,
        "height": 480,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      },
      "thumbnail": {
        "width": 128,
        "height": 128,
        "format": "jpg",
        "url": "https://example.com/some.jpg",
        "secure_url": "https://example.com/some.jpg"
      }
    },
    "AccessType": "rule_access_always"
  },
  "EventID": "44387d09-25e8-4529-96bc-bcb9088e5045",
  "Timestamp": 1663970396948
}

AccessType	Meaning
`rule_access_always`	The user may always use the lock.
`rule_access_temporary`	The user's access is temporary.
`rule_access_recurring`	The user's access is recurring.

Example doorbell webhooks#

Motion detected#

The doorbell detected motion. This event includes a still image taken at the time of the motion.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "DoorbellID": "54b6c08ed4c6",
  "EventType": "doorbell_motion_detected",
  "Url": "http://example.com/some.jpg",
  "SecureURL": "https://example.com/some.jpg",
  "Width": 480,
  "Height": 640
}

Button pressed#

Someone pressed the doorbell button.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "DoorbellID": "54b6c08ed4c6",
  "EventType": "buttonpush",
  "dvrID":"d865a29e-cbd6-4b80-8944-8935d217757e"
}

Video available#

The doorbell recorded a video. It can be downloading using the API or viewed using the August mobile app. This video is recorded after motion is detected or the doorbell button is pressed.

To get the URL of the video, call GET /doorbells/:doorbellID/videoevent?dvrID=<dvrID> which will return

{
  "url": "https://something.cloudfront.net/<uuid>/<doorbellid>/<uuid>/playlist.m3u8"
}

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "DoorbellID": "54b6c08ed4c6",
  "EventType": "doorbell_video_upload_available",
  "dvrID": "d865a29e-cbd6-4b80-8944-8935d217757e",
  "cause": "doorbell_motion_detected",
  "startTime": 1545187132470
}

cause	Meaning
`doorbell_motion_detected`	The doorbell recorded a video because the doorbell detected motion.
`buttonpush`	The doorbell recorded a video because someone pressed the doorbell button.

Example user webhooks#

User added to a lock#

The user was added to a lock.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "timeStamp": 1663019240123,
  "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
  "EventType": "authorization",
  "Event": "lock_user_add",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventID": "bfd056a3-b9e5-4640-b46e-a24c837b4102",
  "Timestamp": 1663019240070
}

User removed from a lock#

The user was removed from a lock.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "timeStamp": 1663018978098,
  "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
  "EventType": "authorization",
  "Event": "lock_user_remove",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventID": "d5ed4c3c-3464-4595-b1f4-7b5fff4d922f",
  "Timestamp": 1663018978087
}

User access level changed#

The user's access level was changed on a lock. For example, from guest to owner.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "timeStamp": 1663019320159,
  "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
  "UserType": "superuser",
  "EventType": "authorization",
  "Event": "lock_usertype_changed",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventID": "654a2c1e-342a-4b6d-8ae1-44d2f0e4bed2",
  "Timestamp": 1663019320114
}

UserType	Meaning
`user`	The user is now a guest.
`superuser`	The user is now an owner.

User access schedule changed#

The user's access schedule was changed on a lock. For example, from always to temporary.

HTTP Headers

Content-Length: 252
Connection: keep-alive
Content-Type: application/json
X-August-Signature: signature
x-my-header: my_secret_value

Body

{
  "timeStamp": 1663019320159,
  "UserID": "4337d8c6-0fda-4068-989c-aba166ae6b9d",
  "EventType": "authorization",
  "Event": "lock_accesstype_changed",
  "AccessType": "rule_access_always",
  "LockID": "1234567890ABCDEF1234567890ABCDEF",
  "EventID": "654a2c1e-342a-4b6d-8ae1-44d2f0e4bed2",
  "Timestamp": 1663019320114
}

AccessType	Meaning
`rule_access_always`	The user may always use the lock.
`rule_access_temporary`	The user's access is temporary.
`rule_access_recurring`	The user's access is recurring.