Allegion Developer Portal

Schlage Home API Best Practices

Welcome to the Schlage Home API Best Practices. Here we will provide some helpful tips for integrating with our APIs for your platform. Please contact your Allegion representative for any additional questions.

Exposing your Schlage Mobile App Devices to API

The Schlage Home API only supports WiFi-enabled devices: Schlage Encode Deadbolt, Encode Plus, and Encode Levers. Devices added to the Schlage Mobile App via bluetooth must complete the WiFi setup in order to see them through the API. You can see all available devices by GET Device List.

Environment-Specific URLs

When developing and deploying applications across multiple environments (such as development, testing, staging, and production), it's important to manage Redirect URLs and Webhook URLs effectively. This helps in tracking, debugging, and maintaining security across different stages of your application lifecycle. We recommend using different Redirect URLs and Webhook URLs.

Use Different Redirect URLs for Each Environment:
Assign unique Redirect URLs for each environment. This ensures that authentication and authorization processes are correctly routed and managed according to the environment being used. For example:
  • Development: https://dev.yourapp.com/callback
  • Testing: https://test.yourapp.com/callback
  • Production: https://yourapp.com/callback
Use Different Webhook URLs or Add Environment Identifiers:
While you can use the same Webhook URL across environments, it's recommended to differentiate them to easily identify the source environment of the incoming requests. You can achieve this by:
  • Assign unique Webhook URLs for each environment:
    • Development: https://dev.yourapp.com/webhook
    • Testing: https://test.yourapp.com/webhook
    • Production: https://yourapp.com/webhook
  • OR, you can append an environment query parameter to the Webhook URL:
    • Development: https://dev.yourapp.com/webhook?env=dev
    • Testing: https://test.yourapp.com/webhook?env=test
    • Production: https://yourapp.com/webhook?env=prod
Benefits:
  • Clarity: Easily identify which environment is sending the webhook.
  • Analytics: Helps in tracking and logging webhook events based on environments.
  • Troubleshooting: Simplifies debugging by providing context about the environment.

Verifying Webhook Signatures

To ensure that webhooks are genuinely coming from our server and have not been tampered with, we provide a mechanism for verifying webhook signatures. Utilizing this verification process is crucial for maintaining the security and reliability of your application's interactions with our API.

Webhook Signature Verification
  • Public Key for Verification: We provide a public key that should be used to verify the signature of each webhook request. This key is consistent across all client environments, ensuring a unified and straightforward verification process.
  • Accessing the Public Key: You can find the public key and detailed instructions on how to implement the verification process in our Webhook Signature Repository.
  • Verification Process: Each webhook sent from our server includes a signature header. This signature is generated using our private key and can be verified using the provided public key. Implement the verification process in your application to ensure that the webhook payload has not been altered and is indeed from our server.

Responding to Webhooks

When your system receives a webhook from our API platform, it is crucial to acknowledge receipt of the event by responding with an appropriate HTTP status code. This ensures that we know the event has been successfully received and processed, and it prevents unnecessary retries on our end.

  • Recommended Response: Respond with any HTTP status code in the 200-299 range. We accept this range of status codes since it indicates successful receipt and processing of the webhook event. This prevents our system from triggering retry logic, which is designed to handle cases where the webhook might not have been received.
  • Additional Considerations:
    • Ensure your endpoint is capable of processing the webhook data quickly to avoid timeouts. If processing takes longer, consider queuing the data and responding immediately. In the case of an error, ensure your system can still respond with a 200-299 status code after logging or handling the error.