Webhook FAQs

Are webhooks configured at the Application level or the Account level?

DoorFlow webhooks are configured at the Application level, but they are scoped and triggered based on the permissions (scopes) granted by the Account holder for that application. This design allows for centralized webhook management while ensuring that webhooks are only sent for accounts that have authorized the application with the relevant scopes.

Here's how it works:

• Application-Level Configuration: Webhooks are set up at the application level, meaning a single webhook URL is used for all accounts that the application interacts with.
• Account-Specific Scoping: Only accounts with valid OAuth tokens and the necessary scopes (e.g., account.person or account.channel.readonly) will trigger webhooks. This ensures that the application receives only the events it is authorized to access.

Each webhook request includes an account_id, which uniquely identifies the account that generated the event. This enables developers to:

• Identify which account the event is associated with and use the corresponding token to access additional resources, if needed.
• Link the event to their own third-party database records for better organization and multi-tenancy support.
• Decide programmatically whether to process or ignore specific events based on the account.

This approach eliminates the need for state-specific URLs or account-specific webhook configurations, as the account_id in the payload provides sufficient context for handling multi-tenancy effectively.

Does the current webhook implementation send all events for all accounts indiscriminately?

No, webhooks are sent only for accounts where:

• The application has a valid OAuth token for that account.
• The token includes the events.readonly scope.

Webhooks are not sent indiscriminately. If a specific account does not grant the required permissions, no events will be sent for that account. This setup ensures that webhooks are scoped and minimizes unnecessary traffic.

How can I manage selective webhook monitoring for different clients?

To send only the necessary webhook events for each client:

1. Request Specific Scopes Per Client:
   • For Client A, request a token with only the account.person scope to receive credential changes.
   • For Client B, request a token with only the account.channel.readonly scope to receive access events.
2. No Irrelevant Webhooks: Webhooks will only be sent for accounts where the valid token includes the required scope. By carefully managing the requested scopes, you can avoid receiving unnecessary webhook traffic.
3. Centralized Filtering (Optional): If you use a single token with multiple scopes, use the account_id in webhook payloads to filter events client-side.

Do API-triggered changes generate webhooks?

Yes, all changes—whether initiated via the DoorFlow API or the user interface—generate the same webhook events. This ensures consistency in event notifications, regardless of the source of the change.

For example:

• Modifying a credential via the API will trigger a webhook.
• Modifying a credential via Mobile Access will also trigger a webhook.

This behavior ensures that applications remain up-to-date with all relevant events.

Do I need multiple applications to handle different webhook scenarios?

No, you do not need to create multiple applications. A single application can request different scopes when obtaining OAuth tokens, allowing you to handle various webhook scenarios effectively. For example:

• Use one token with account.person scope to receive credential change events.
• Use another token with account.channel.readonly scope to receive door access events.

This flexibility eliminates the need for multiple applications and simplifies webhook management.

Why isn’t state included in webhook URLs?

State is not required in webhook URLs because each webhook payload includes an account_id. This account_id uniquely identifies the account generating the event, allowing you to:

• Determine if the account is one you wish to process webhooks for.
• Associate the event with your own third-party database records.
• Identify which access token to use for requesting additional event details.

By relying on account_id, the need for state-specific URLs is removed, streamlining the webhook implementation.

How can I optimize webhook handling for a specific client?

If you only need to receive specific events for a single client:

1. Request only the necessary scopes when obtaining the OAuth token for that account.
2. Filter incoming webhook events client-side using the account_id in the payload.

This approach ensures that you process only the events relevant to your client without requiring additional applications or configurations.

Summary of Best Practices for DoorFlow Webhooks

• Use Scopes: Control which events are sent by managing OAuth token scopes.
• Leverage account_id: Use the account_id in webhook payloads to handle multi-tenancy and associate events with your database records.
• Single Application: Avoid creating multiple applications; use scopes to tailor webhook behavior for specific accounts.
• Process Webhooks Client-Side: Implement filtering logic based on account_id to ensure you only handle relevant events.

By following these best practices, you can efficiently manage webhooks and reduce unnecessary complexity in your application.

If you have further questions or encounter issues, feel free to contact our support team or refer to the Webhook API Documentation.