Webhook Events Reference
Bynn provides a comprehensive set of webhook events that enable organizations to receive real-time notifications about every aspect of the identity verification process. This reference guide details all 43 subscribable webhook events available in the Bynn platform, organized by functional category to support efficient event selection and integration planning.
Event Subscription Overview
Organizations can selectively subscribe to specific webhook events based on their integration requirements and business workflows. The Bynn platform automatically subscribes new webhook endpoints to five essential events that cover the most common verification scenarios, while providing granular control over additional event subscriptions for specialized use cases.
Default subscription events include fundamental verification milestones such as dossier creation, decision outcomes, and anti-money laundering screening results. Organizations can expand their event subscriptions to include detailed session tracking, document processing updates, and specialized compliance events based on their specific operational requirements and integration architecture.
Event Categories and Descriptions
Dossier Events
Dossier events represent the primary case lifecycle in Bynn's identity verification system, providing comprehensive updates about verification case progression from initiation through final resolution. These events enable organizations to track verification cases through their complete lifecycle and implement appropriate business logic based on case status changes.
| Event Name | Default Subscribe | Description |
|---|---|---|
dossier.created | ✅ | Occurs whenever a new dossier is created |
dossier.open | ❌ | Indicates that the dossier is currently being processed |
dossier.completed | ❌ | Triggered when a dossier has been fully processed and completed |
dossier.canceled | ❌ | Indicates that the dossier process has been canceled |
dossier.archived | ❌ | Triggered when a dossier is archived for future reference |
dossier.expired | ❌ | Indicates that the dossier has expired and is no longer valid |
dossier.approved | ❌ | Triggered when a dossier has been reviewed and approved |
dossier.rejected | ❌ | Occurs when a dossier is reviewed and rejected |
dossier.needs_attention | ❌ | Indicates that a dossier requires manual review or further action |
The dossier.created event serves as the foundation for case tracking systems and enables immediate initialization of customer onboarding workflows. Organizations typically use this event to create customer records, initiate background processes, and establish audit trails for compliance purposes. The event includes comprehensive case metadata that supports immediate workflow decisions and routing logic.
Completion and resolution events including dossier.completed, dossier.approved, and dossier.rejected provide definitive case outcomes with detailed verification results and supporting evidence. These events enable organizations to implement final onboarding decisions, compliance reporting, and customer communication workflows based on verification outcomes.
Status management events such as dossier.open, dossier.canceled, dossier.archived, and dossier.expired provide visibility into case progression and enable efficient queue management and operational monitoring. Organizations can use these events to implement appropriate customer communication, case management workflows, and compliance documentation requirements.
Entity Events
Entity events provide notifications about business entity management within the Bynn platform, supporting scenarios where organizations need to track entity creation and deletion for compliance and operational purposes.
| Event Name | Default Subscribe | Description |
|---|---|---|
entity.created | ❌ | Triggered when a new entity is added to the system |
entity.deleted | ❌ | Occurs when an entity is deleted from the system |
Entity events support business entity verification workflows and compliance requirements that involve tracking entity relationships, ownership structures, and regulatory obligations. Organizations implementing entity verification processes can use these events to maintain comprehensive entity records and support complex compliance reporting requirements.
Decision Events
Decision events provide granular information about automated and manual verification decisions within the Bynn platform, enabling organizations to implement sophisticated business logic based on decision outcomes and confidence levels.
| Event Name | Default Subscribe | Description |
|---|---|---|
decision.approved | ✅ | Indicates that a decision has been reviewed and approved |
decision.rejected | ✅ | Triggered when a decision is reviewed and rejected |
decision.challenge | ✅ | Indicates that a decision is being challenged or requires further review |
The decision.approved event provides detailed approval information including confidence scores, verification factors, and compliance confirmations that support immediate customer onboarding and access provisioning. Organizations can use approval events to trigger automated account activation, service provisioning, and customer welcome workflows.
The decision.rejected event includes comprehensive rejection reasoning, failed verification elements, and recommendations for customer communication or resubmission workflows. Organizations can implement sophisticated rejection handling including targeted customer support, resubmission guidance, and fraud detection workflows based on rejection reasons.
The decision.challenge event indicates scenarios where verification processes encounter ambiguous results that require additional verification steps or manual review. These events enable organizations to implement specialized workflows for edge cases while maintaining efficient processing for straightforward verification scenarios.
AML Screening Events
Anti-Money Laundering screening events provide critical updates about watchlist screening and compliance processes, enabling organizations to implement immediate risk management and compliance procedures.
| Event Name | Default Subscribe | Description |
|---|---|---|
aml.screening.match | ✅ | Triggered when an AML screening match is found |
The aml.screening.match event delivers immediate alerts when customers match watchlist entries, sanctions lists, or adverse media coverage, enabling organizations to implement appropriate risk management and compliance procedures immediately upon detection. These events include detailed match information, confidence scores, and recommended actions that support compliance teams in making informed decisions about customer risk levels and appropriate due diligence measures.
Session Events
Session events track customer interaction and progression through Bynn's verification interface, providing insights into customer experience and verification flow completion rates that support user experience optimization and operational monitoring.
| Event Name | Default Subscribe | Description |
|---|---|---|
session.created | ❌ | Occurs whenever a new session is initiated |
session.completed | ❌ | Triggered when a session is successfully completed |
session.canceled | ❌ | Indicates that the session has been canceled |
session.expired | ❌ | Occurs when a session expires before completion |
Session lifecycle events enable organizations to track customer engagement patterns, identify optimization opportunities, and implement appropriate customer support workflows. The session.created event provides immediate visibility into verification initiation and enables real-time customer experience monitoring and support queue management.
Completion and resolution events including session.completed, session.canceled, and session.expired provide detailed session outcome data and timing information that supports customer experience optimization and abandonment analysis. Organizations can use this data to optimize verification flows, implement targeted customer support, and identify technical issues that impact completion rates.
Session Consent Events
Consent tracking events provide detailed records of customer consent decisions, supporting compliance with data protection regulations and audit requirements while enabling organizations to implement appropriate data handling workflows.
| Event Name | Default Subscribe | Description |
|---|---|---|
session.consent.accept | ❌ | Triggered when a user accepts the consent agreement |
session.consent.reject | ❌ | Occurs when a user rejects the consent agreement |
Consent events include comprehensive metadata about consent types, consent content, and customer decision timing that supports detailed compliance documentation and audit trail maintenance. Organizations can use consent events to implement appropriate data processing workflows, compliance reporting, and customer preference management based on specific consent decisions.
Session ID Document Events
ID document session events provide detailed tracking of document capture and processing during verification sessions, enabling organizations to monitor document collection success rates and implement targeted customer support for document-related issues.
Front Document Events
| Event Name | Default Subscribe | Description |
|---|---|---|
session.id_document_front.received | ❌ | Triggered when the front side of an ID document is received |
session.id_document_front.accepted | ❌ | Indicates that the front side of the ID document has been verified and accepted |
session.id_document_front.rejected | ❌ | Occurs when the front side of the ID document is rejected |
Back Document Events
| Event Name | Default Subscribe | Description |
|---|---|---|
session.id_document_back.received | ❌ | Triggered when the back side of an ID document is received |
session.id_document_back.accepted | ❌ | Indicates that the back side of the ID document has been verified and accepted |
session.id_document_back.rejected | ❌ | Occurs when the back side of the ID document is rejected |
Document capture events enable organizations to track document collection success rates, identify common capture issues, and implement targeted customer guidance for document quality improvement. The separation between front and back document events supports detailed analysis of document capture patterns and optimization of user interface guidance.
Document acceptance and rejection events provide immediate feedback about document quality and processing outcomes, enabling organizations to implement real-time customer support and guidance workflows that improve verification completion rates and customer experience.
Session Liveness Events
Liveness detection events provide real-time updates about biometric verification processes and anti-spoofing measures, enabling organizations to track biometric collection success rates and implement appropriate fraud prevention workflows.
| Event Name | Default Subscribe | Description |
|---|---|---|
session.liveness.started | ❌ | Indicates that a liveness check has been initiated |
session.liveness.accepted | ❌ | Triggered when the liveness check is successfully verified |
session.liveness.rejected | ❌ | Occurs when the liveness check fails verification |
Liveness events include detailed information about biometric quality, anti-spoofing measures, and verification confidence levels that support sophisticated fraud detection and customer experience optimization. Organizations can use liveness events to implement risk-based authentication workflows and targeted customer support for biometric collection issues.
Session Proof of Address Events
Proof of address session events provide tracking for address verification document collection during verification sessions, supporting comprehensive address verification workflows and compliance requirements.
| Event Name | Default Subscribe | Description |
|---|---|---|
session.poa.received | ❌ | Triggered when a proof of address document is received |
session.poa.accepted | ❌ | Indicates that the proof of address has been verified and accepted |
session.poa.rejected | ❌ | Occurs when the proof of address is rejected |
Address verification events enable organizations to track address document collection success rates, implement targeted customer guidance for address verification requirements, and support comprehensive compliance workflows that require address verification documentation.
Identity Document Events
Identity document events provide detailed updates about document processing, analysis, and verification outcomes throughout the document analysis pipeline, enabling organizations to track document verification progress and implement appropriate business logic based on document analysis results.
| Event Name | Default Subscribe | Description |
|---|---|---|
identity_document.approved | ❌ | Triggered when an identity document is verified and approved |
identity_document.rejected | ❌ | Occurs when an identity document is reviewed and rejected |
identity_document.analyzed | ❌ | Indicates that an identity document has undergone forensic analysis |
identity_document.expired | ❌ | Triggered when an identity document has expired |
identity_document.needs_attention | ❌ | Indicates that an identity document requires further review |
identity_document.in_bynn_review_queue | ❌ | Indicates that an identity document is in Bynn's manual review queue |
Document analysis events including identity_document.analyzed provide detailed forensic analysis results, extracted data, and authenticity assessments that enable immediate data processing while verification workflows continue. Organizations can use analysis events to populate customer databases, implement fraud detection workflows, and support compliance documentation requirements.
Document resolution events including identity_document.approved and identity_document.rejected provide definitive document verification outcomes with detailed analysis results, security feature validation, and fraud detection insights. These events support final verification decisions and customer communication workflows.
Status management events such as identity_document.needs_attention and identity_document.in_bynn_review_queue provide visibility into manual review processes and enable efficient queue management and customer communication about processing timelines.
Proof of Address Events
Proof of address events provide specialized updates for address verification workflows that complement identity document verification, supporting comprehensive customer verification requirements and compliance obligations.
| Event Name | Default Subscribe | Description |
|---|---|---|
proof_of_address.approved | ❌ | Triggered when a proof of address document is verified and approved |
proof_of_address.rejected | ❌ | Occurs when a proof of address document is reviewed and rejected |
proof_of_address.analyzed | ❌ | Indicates that a proof of address document has undergone analysis |
proof_of_address.expired | ❌ | Triggered when a proof of address document has expired |
proof_of_address.needs_attention | ❌ | Indicates that a proof of address document requires further review |
Address verification events enable organizations to implement comprehensive address verification workflows, track address document processing progress, and support compliance requirements that mandate address verification documentation. These events provide detailed address extraction results, document authenticity assessments, and verification outcomes that support customer onboarding and compliance reporting.
Document Analysis Events
General document analysis events provide comprehensive updates for document processing workflows that encompass multiple document types and verification scenarios.
| Event Name | Default Subscribe | Description |
|---|---|---|
document.analyzed | ❌ | Occurs whenever a document has been analyzed and the results are ready |
The document.analyzed event provides comprehensive analysis results for various document types including identity documents, proof of address documents, and specialized verification documents. Organizations can use this event to implement unified document processing workflows that handle multiple document types through consistent processing logic.
Event Subscription Strategy
Default Event Selection
The five default subscription events provide comprehensive coverage of essential verification milestones that support the majority of customer onboarding and compliance workflows. Organizations implementing basic verification workflows can rely on default events for immediate integration while expanding event subscriptions based on specific operational requirements.
Default events include case initiation tracking through dossier.created, comprehensive decision outcomes through decision.approved, decision.rejected, and decision.challenge, and critical compliance alerts through aml.screening.match. This combination provides complete visibility into verification outcomes while minimizing webhook volume for organizations with straightforward integration requirements.
Specialized Event Selection
Organizations with specialized requirements can expand their event subscriptions to include detailed session tracking, document processing updates, and granular status management events. Session-level events support detailed customer experience optimization and real-time customer support workflows, while document-level events enable sophisticated document processing automation and quality management.
Compliance-focused organizations may benefit from comprehensive event subscriptions that include all AML events, detailed consent tracking, and complete audit trail events that support regulatory reporting and compliance documentation requirements. Financial services organizations typically implement expanded event subscriptions to support enhanced due diligence and ongoing monitoring requirements.
Integration Architecture Considerations
Event subscription strategy should align with integration architecture and processing capacity to ensure efficient webhook processing and reliable business workflow execution. High-volume organizations may benefit from selective event subscriptions that focus on business-critical events while implementing periodic API polling for detailed status information and reporting data.
Organizations implementing event-driven architectures can leverage comprehensive event subscriptions to support sophisticated business process automation, real-time analytics, and customer experience optimization through immediate response to verification events and customer interactions.
Implementation Guidelines
Event Processing Patterns
Webhook event processing should implement appropriate filtering, routing, and transformation logic based on event types and organizational requirements. Events can be processed through unified handlers that implement common processing logic, or through specialized handlers that optimize processing for specific event types and business workflows.
Organizations should implement appropriate event deduplication, ordering, and retry logic to ensure reliable event processing and maintain data consistency across systems. Event processing architecture should support both real-time processing for time-sensitive events and batch processing for analytics and reporting workflows.
Monitoring and Analytics
Event subscription monitoring should track event volume patterns, processing success rates, and business impact metrics to optimize subscription strategy and identify integration improvement opportunities. Organizations can use event analytics to understand verification patterns, optimize customer experience, and identify operational improvement opportunities.
Comprehensive event logging and audit trails support compliance requirements and enable detailed analysis of verification workflows, customer behavior patterns, and system performance characteristics that inform ongoing optimization and enhancement efforts.
Updated 6 days ago