Application Onboarding Webhook Integration Guide

Step-by-step guidance for integrating with Dorman Application Onboarding Webhooks, including webhook registration, callback events, payload structure, and authentication.

The Application Onboarding Webhook integration allows brokers to receive real-time notifications about application onboarding activity without continuously polling the Dorman APIs.

The integration supports:

  • Individual applications

  • Joint applications

  • Application creation

  • Application opening

  • Application status changes

  • Required document completion

To receive Application Onboarding webhook notifications, the broker must register a webhook using the Generic Webhook Registration API with:

"webhookType": "APPLICATION"

For webhook registration, deregistration, and supported webhook types, refer to the Webhook API Updates and Migration Guide.

1. Application Webhook Overview

Once an Application webhook is registered, Dorman sends webhook notifications to the broker's registered webhookUrl when applicable application events occur.

The general flow is:

Application Created / Updated           
           ↓ 
Application Event Generated           
           ↓ 
 Dorman Webhook Processing           
           ↓ 
     Webhook Callback           
           ↓ 
   Broker Webhook Endpoint

Does not need to continuously poll the application status to receive these notifications.

2. Register/De-register for Application Webhooks

Application webhooks are registered using the Generic Webhook Registration API.

Endpoint:

POST /api/webhook/register

Set the webhook type to:

"webhookType": "APPLICATION"

Example Request:

{   
"webhookType": "APPLICATION",   
"webhookUrl": "https://broker.example.com/webhooks/application",   
"webhookAuthenticationKey": "broker-supplied-key",   
"webhookSecret": "broker-supplied-secret",   
"notificationEmail": "ops@broker.example.com" 
}

After successful registration, Dorman will send applicable Application Onboarding events to the registered webhook URL.

For complete registration request/response details, see the Webhook API Guide.

3. Application Webhook Events

The following events may be sent to the registered Application webhook.

APPLICATION_IN_PROGRESS-Application has been created and is in progress.

APPLICATION_OPENED-Application has been opened.

APPLICATION_STATUS_CHANGED-Application status has changed.

APPLICATION_COMPLETE-Application document completion event.

3.1 Application Status Changes

APPLICATION_STATUS_CHANGED may be generated when the application status changes to statuses such as:

  • Submitted

  • Approved

  • Declined

  • Rejected

  • Processing

  • Other applicable statuses

4. Application Types

Application webhook notifications support both Individual and Joint applications.

4.1 Individual Application

An Individual application contains the application's own ID and does not contain joint application reference fields.

Example

{   
"callback_type": "APPLICATION",
"event_type": "APPLICATION_IN_PROGRESS",   
"application_id": 12345,   
"application_type": "INDIVIDUAL",   
"status": "INPROGRESS",   
"message": "Application created successfully.",   
"error_list": [],   
"occurred_at": "2026-06-17T05:00:00Z" 
}

4.2 Joint Application – Primary

For a primary Joint application, the payload includes the secondary_application_id.

{   
"callback_type": "APPLICATION",
"event_type": "APPLICATION_IN_PROGRESS",   
"application_id": 70593,   
"secondary_application_id": 70594,   
"application_type": "JOINT",   
"status": "INPROGRESS",   
"message": "Joint application created successfully.",   
"error_list": [],  
"occurred_at": "2026-06-17T05:00:00Z" 
}

4.3 Joint Application – Secondary

For a secondary Joint application, the payload includes the primary_application_id.

{   
"callback_type": "APPLICATION",
"event_type": "APPLICATION_IN_PROGRESS",   
"application_id": 70594,   
"primary_application_id": 70593,   
"application_type": "JOINT",   
"status": "INPROGRESS",   
"message": "Joint application created successfully.",   
"error_list": [],  
"occurred_at": "2026-06-17T05:00:00Z" 
}

The cross-reference fields allow the broker to identify the relationship between the primary and secondary applications.

5. Webhook Payload

Application webhook payloads contain common fields and may contain additional fields depending on the application type and event.

Common Payload Fields

  • callback_type – Type of webhook.

  • event_type – Type of application webhook event.

  • application_id – Unique application ID.

  • application_type – Indicates whether the application is Individual or Joint.

  • status – Current application status.

  • message – Human-readable description of the event.

  • error_list – Missing document or validation information, when applicable.

  • occurred_at – Event timestamp.

Conditional Fields

  • account_number – Included when an account number has been assigned.

  • secondary_application_id – Included for a primary Joint application.

  • primary_application_id – Included for a secondary Joint application.

Fields that are not applicable are omitted from the payload.

6. Document Completion

  • Dorman can send an APPLICATION_COMPLETE event related to the application's required document status.

  • When all required documents are uploaded, the Application webhook is generated with the applicable application information.

  • If required documents are missing, the error_list identifies the missing documents.

Example:

{   
"callback_type": "APPLICATION",
"event_type": "APPLICATION_COMPLETE",   
"application_id": 70594,   
"primary_application_id": 70593,   
"application_type": "JOINT",   
"status": "INPROGRESS",   
"message": "Required documents are missing. See ErrorList for details.",   
"occurred_at": "2026-06-17T05:00:00Z",   
"error_list": [     "Risk Disclosure Statement",     "Government ID"   ] 
}

7. Example Application Webhook Callback (Dorman -> Broker)

A complete callback from Dorman to the broker will look similar to:

POST /your/webhook/endpoint HTTP/1.1 
Content-Type: application/json 
Authorization: api-key <YOUR_WEBHOOK_AUTHENTICATION_KEY> 
X-Dorman-Signature: <64-character-lowercase-hex-signature>  
{   
"callback_type": "APPLICATION",
"event_type": "APPLICATION_IN_PROGRESS",   
"application_id": 70594,   
"primary_application_id": 70593,   
"application_type": "JOINT",   
"status": "INPROGRESS",   
"message": "Joint application created successfully.",   
"error_list": [],  
"occurred_at": "2026-06-17T05:00:00Z" 
}

The broker should validate the authentication headers and HMAC signature before processing the payload.