Webhook API Guide

1. Overview

To simplify webhook management and provide a consistent integration experience, the Generic Webhook Registration API.

The API provides a single set of endpoints that can be used to register, deregister, and retrieve the registration status of supported webhook types.

2. Generic Webhook API

The following endpoints are now available:

  1. POST /api/webhook/register – Register or update a webhook registration.

  2. DELETE /api/webhook/register?webhookType={Webhook-Type} – Deregister a specific webhook type.

  3. GET /api/webhook/register – Retrieve webhook registration status.

The same endpoint is used for different webhook types. The webhookType identifies which webhook registration is being managed.

3. Webhook Types

The Generic Webhook API currently supports the following webhook types:

1. TREASURY_SETUP – Used to configure and receive ACH status change notifications.

2.APPLICATION – Used for application onboarding and to receive updates related to application status changes throughout the onboarding process.

The webhookType value is case-insensitive.

4. Register or Update Webhook

4.1 Endpoint

POST /api/webhook/register

4.2 Request Body

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

4.3 Request Properties

  1. webhookType – Required. Identifies the type of webhook being registered.

  2. webhookUrl – Required. URL where webhook notifications should be delivered.

  3. webhookAuthenticationKey – Required. Broker-supplied authentication key.

  4. webhookSecret – Required. Broker-supplied secret used for HMAC-SHA256 signature validation.

  5. notificationEmail – Required. Email address used for webhook-related notifications.

4.4 Webhook Callback Authentication

Once a webhook is registered, Dorman will send webhook notifications to the registered webhookUrl.

Each webhook request contains two security headers:

  • Authorization

  • X-Dorman-Signature

Should validate both headers before processing the webhook payload.

4.4.1 Authorization Header

Dorman includes the webhook authentication key provided during webhook registration in the Authorization HTTP header.

Authorization: api-key <YOUR_WEBHOOK_AUTHENTICATION_KEY>

The webhook authentication key is separate from the webhook secret.

The authentication key is sent in the Authorization header when delivering webhook notifications.

4.4.2 HMAC-SHA256 Signature

Each webhook request also contains an X-Dorman-Signature header.

X-Dorman-Signature: <64-character-lowercase-hex-signature>

The signature is generated using:

  • Message: Exact raw JSON request body

  • HMAC Key: Webhook secret provided during registration

  • Algorithm: HMAC-SHA256

The resulting signature is a 64-character lowercase hexadecimal string.

Example:

X-Dorman-Signature: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Calculate the HMAC-SHA256 signature using registered webhook secret and compare it with the value received in X-Dorman-Signature.

4.4.3 Webhook Secret

  • The webhookSecret is provided during webhook registration.

  • The secret can be any valid UTF-8 string, including alphanumeric, hexadecimal, or Base64-looking values.

  • The exact string provided during registration is converted to UTF-8 bytes and used as the HMAC-SHA256 key.

4.4.4 Example Webhook Request (Dorman -> Broker)

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>  
{   
// Payload for the corresponding webhook event
}

4.5 Example Registration API Response

{   
"success": true,   
"message": "Webhook registration updated successfully for TREASURY_SETUP.",   
"data": 
{     
"webhookType": "TREASURY_SETUP",     
"webhookUrl": "https://broker.example.com/webhooks/dorman",     
"notificationEmail": "ops@broker.example.com",     
"isEnabled": true,     
"registeredAt": "2026-08-12T07:29:20.7239878Z",     
"updatedAt": "2026-08-12T07:29:20.7239878Z"   
} 
}

5. Deregister Webhook

The Generic Webhook API also uses the same /api/webhook/register endpoint for deregistration.

The webhook type must be provided as a query parameter to identify which webhook registration should be disabled.

5.1 Endpoint

DELETE /api/webhook/register?webhookType={Webhook-Type}

5.2 Example – Deregister ACH Setup Webhook

DELETE /api/webhook/register?webhookType=TREASURY_SETUP 
Ocp-Apim-Subscription-Key: {api_key}

5.3 Example Response

{   
"data": 
 {     
    "webhookType": "TREASURY_SETUP",     
    "deregisteredAt": "2026-08-12T07:29:20.7239878Z"   
 },   
"success": true,   
"message": "TREASURY_SETUP webhook deregistered successfully. No further notifications will be sent. Call POST /api/webhook/register to re-enable.",   
"errorList": [] 
}

After deregistration, no further notifications will be sent for that webhook type.

To re-enable the webhook, use the POST /api/webhook/register endpoint again.

6. Retrieve Webhook Registration

The registration status for supported webhook types can be retrieved using the generic GET endpoint.

6.1 Endpoint

GET /api/webhook/register
Ocp-Apim-Subscription-Key: {api_key}

☰