MyDataboss Webhooks - API Reference

On this page Overview Subscribing Request Format Verifying Signatures Delivery & Retries Event Catalogue

Overview

MyDataboss webhooks let your systems react to events as they happen - an onboarding completing, an AML screening finishing, a client's status changing - without polling our API. When a subscribed event occurs, we send an HTTP POST to the URL you registered, carrying a JSON body and a signature you can verify.

sequenceDiagram
    participant SRC as MyDataboss Event
    participant DISP as Webhook Dispatcher
    participant EP as Your Endpoint
    SRC->>DISP: Event occurs (e.g. onboarding.completed)
    DISP->>DISP: Find active subscriptions for this event + business
    DISP->>DISP: Sign body with HMAC-SHA256 (your secret)
    DISP->>EP: POST JSON + headers
    EP-->>DISP: 2xx = delivered
    Note over DISP,EP: Non-2xx or timeout -> retry with backoff (up to MaxRetries)

Every delivery is a POST with Content-Type: application/json.
Events are scoped to your business (tenant) - you only receive events for your own data.
Each request is signed so you can confirm it genuinely came from MyDataboss.
Failed deliveries are retried; each event carries a unique id so you can de-duplicate safely.

Subscribing to Events

A webhook subscription tells MyDataboss where to send events and which events you want. Subscriptions are managed per business and have the following properties:

Field	Required	Description
`name`	Yes	A friendly label for the subscription.
`url`	Yes	Your HTTPS endpoint. HTTP is not supported.
`eventTypes`	Yes	The event names you want delivered (e.g. `onboarding.completed`, `client.status.changed`). Subscribe to one or many.
`secret`	Recommended	A shared secret used to sign each request. Store it securely; you will need it to verify signatures.
`maxRetries`	Optional	How many times a failed delivery is retried. Defaults to 3.
`isActive`	Optional	Enable or disable the subscription without deleting it. Defaults to true.

Tip: Your endpoint should respond with a 2xx status as quickly as possible. Do the heavy work asynchronously - acknowledge first, process after - so a slow handler does not trigger unnecessary retries.

Request Format & Headers

Every webhook is delivered as:

POST https://your-endpoint.example.com/webhooks
Content-Type: application/json

Headers

Header	Description
`X-MyDataboss-Event`	The event type, e.g. `onboarding.completed`.
`X-Event-Id`	Unique id for this event. Use it to de-duplicate retries.
`X-Tenant-Id`	The business / tenant the event belongs to.
`X-Retry-Count`	Attempt number for this delivery, starting at 1.
`X-MyDataboss-Signature`	Lowercase hex HMAC-SHA256 signature of the raw request body. See Verifying Signatures.

Body envelope

Every payload includes two envelope fields in addition to the event-specific fields below:

Field	Description
`webhook_type`	The event name, mirroring the `X-MyDataboss-Event` header.
`time`	Timestamp the event was dispatched.

Note: All payload values are delivered as strings (including booleans like "true" and numbers like "42"). Parse/cast on your side as needed.

Verifying Signatures

Each request includes an X-MyDataboss-Signature header so you can confirm it came from MyDataboss and was not tampered with. The signature is an HMAC-SHA256 of the raw request body, keyed with your subscription secret, hex-encoded in lowercase.

Compute the HMAC over the exact raw bytes of the body you received (do not re-serialise the JSON).
Compare using a constant-time comparison to avoid timing attacks.
Reject the request if the signatures do not match.

Node.js

// express raw body required: app.use(express.raw({ type: 'application/json' }))
const crypto = require('crypto');
function verify(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

C#

using System.Security.Cryptography;
using System.Text;
bool Verify(string rawBody, string signatureHeader, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawBody));
    var expected = Convert.ToHexString(hash).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.UTF8.GetBytes(expected), Encoding.UTF8.GetBytes(signatureHeader));
}

Important: Always set a secret on production subscriptions and verify every request. Treat unsigned or mismatched requests as untrusted and discard them.

Delivery, Retries & Idempotency

Behaviour	Detail
Success	Any HTTP `2xx` response marks the event delivered.
Retries	Non-2xx responses and timeouts are retried up to `maxRetries` (default 3), with backoff between attempts. The `X-Retry-Count` header tells you which attempt this is.
Dead-letter	After retries are exhausted, the delivery is recorded as failed and the subscription may be auto-disabled until you re-enable it.
Idempotency	The same event may arrive more than once. De-duplicate using `X-Event-Id` - process each id at most once.
Ordering	Delivery order is not guaranteed. Use the `time` field and your own state to reconcile.

flowchart LR
    A[Deliver attempt] --> B{2xx?}
    B -->|Yes| C([Delivered])
    B -->|No| D{Attempts left?}
    D -->|Yes| E[Wait backoff] --> A
    D -->|No| F([Dead-lettered
subscription disabled])
    classDef teal fill:#042f34,stroke:none,color:#fff
    classDef green fill:#dcfce7,stroke:#bbf7d0,color:#166534
    classDef red fill:#fee2e2,stroke:#fca5a5,color:#991b1b
    classDef amber fill:#fef3c7,stroke:#fde68a,color:#92400e
    class A,D,E teal
    class B amber
    class C green
    class F red

Event Catalogue

Events are grouped by topic. Subscribe to the specific event names you need. Remember every payload also carries the webhook_type and time envelope fields shown earlier. Example values are illustrative; all values are delivered as strings.

Topic Onboarding

onboarding.completedOnboarding

Fires when fires when a customer finishes onboarding (mobile, hosted iframe, or API), including returning customers completing a designated-service form.

Field	Description
`customer_mdb_id`	The customer's MyDataboss ID.
`action`	Always 'accepted'.
`source`	Where onboarding occurred, e.g. MOBILE, IFRAME_ONBOARDING.
`aml_screening_initiated`	'true' / 'false' - whether an AML check was started.
`customer_identifier` optional	Your reference for the customer (API-initiated onboarding only).
`is_existing_customer` optional	'true' for returning customers (API-initiated onboarding only).

{
  "webhook_type": "onboarding.completed",
  "time": "2026-06-05T14:32:10+10:00",
  "customer_mdb_id": "A1B2C3",
  "action": "accepted",
  "source": "string",
  "aml_screening_initiated": "false",
  "customer_identifier": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "is_existing_customer": "false"
}

onboarding.failedOnboarding

Fires when fires when verification is rejected or sent to manual review.

Field	Description
`given_names`	Customer given names.
`surname`	Customer surname.
`email_address`	Customer email.
`mobile`	Customer mobile number.
`onboarding_request_id`	Id of the onboarding / KYC session.
`verification_type`	'NEW' or 'RENEWAL'.
`reason`	JSON array of error objects describing why it failed.

{
  "webhook_type": "onboarding.failed",
  "time": "2026-06-05T14:32:10+10:00",
  "given_names": "string",
  "surname": "string",
  "email_address": "jane@example.com",
  "mobile": "+61400000000",
  "onboarding_request_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "verification_type": "string",
  "reason": "string"
}

onboarding.declinedOnboarding

Fires when fires when a customer declines / rejects an onboarding invitation.

Field	Description
`customer_mdb_id`	The customer's MyDataboss ID.
`action`	Always 'rejected'.
`aml_screening_initiated`	'true' / 'false'.

{
  "webhook_type": "onboarding.declined",
  "time": "2026-06-05T14:32:10+10:00",
  "customer_mdb_id": "A1B2C3",
  "action": "accepted",
  "aml_screening_initiated": "false"
}

client.status.changedOnboarding

Fires when fires when any of a client's three onboarding statuses changes - KYC, AML, or Designated Service. A single event reports all three with before/after values and per-status changed flags.

Field	Description
`mdb_id`	The customer's MyDataboss ID.
`changed_at`	ISO-8601 timestamp of the change.
`kyc_status`	Current KYC status.
`kyc_status_prior`	Previous KYC status.
`kyc_changed`	'true' / 'false'.
`aml_status`	Current AML status.
`aml_status_prior`	Previous AML status.
`aml_changed`	'true' / 'false'.
`designated_service_status`	Current Designated Service status.
`designated_service_status_prior`	Previous Designated Service status.
`designated_service_changed`	'true' / 'false'.

{
  "webhook_type": "client.status.changed",
  "time": "2026-06-05T14:32:10+10:00",
  "mdb_id": "A1B2C3",
  "changed_at": "2026-06-05T05:01:44.000Z",
  "kyc_status": "string",
  "kyc_status_prior": "string",
  "kyc_changed": "false",
  "aml_status": "string",
  "aml_status_prior": "string",
  "aml_changed": "false",
  "designated_service_status": "string",
  "designated_service_status_prior": "string",
  "designated_service_changed": "false"
}

Topic Data Requests

datarequest.submittedData Request

Fires when fires when a customer submits a data request form.

Field	Description
`mdb_id`	The customer's MyDataboss ID.
`form_id`	Id of the submitted form version.
`form_name`	Human-readable form name.
`form_version`	Form version number.

{
  "webhook_type": "datarequest.submitted",
  "time": "2026-06-05T14:32:10+10:00",
  "mdb_id": "A1B2C3",
  "form_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "form_name": "string",
  "form_version": "3"
}

ds.submittedData Request

Fires when fires when a returning customer submits a designated-service form during the onboarding shortcut.

Field	Description
`customer_mdb_id`	The customer's MyDataboss ID.
`form_id`	Id of the submitted form version.
`form_name`	Form name.
`form_version`	Form version number.
`source`	Where it was submitted, e.g. ONBOARDING_IFRAME.

{
  "webhook_type": "ds.submitted",
  "time": "2026-06-05T14:32:10+10:00",
  "customer_mdb_id": "A1B2C3",
  "form_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "form_name": "string",
  "form_version": "3",
  "source": "string"
}

Topic Verification

customer.verification.succeededVerification

Fires when fires when a customer accepts a verification challenge (e.g. a presence check).

Field	Description
`action`	Always 'accept'.
`mdb_customer_id`	The customer's MyDataboss ID (empty if the user is not yet verified).

{
  "webhook_type": "customer.verification.succeeded",
  "time": "2026-06-05T14:32:10+10:00",
  "action": "accepted",
  "mdb_customer_id": "A1B2C3"
}

customer.verification.failedVerification

Fires when fires when a customer fails or declines a verification challenge.

Field	Description
`action`	Always 'declined'.
`mdb_customer_id`	The customer's MyDataboss ID (empty if the user is not yet verified).

{
  "webhook_type": "customer.verification.failed",
  "time": "2026-06-05T14:32:10+10:00",
  "action": "accepted",
  "mdb_customer_id": "A1B2C3"
}

verification.eventVerification

Fires when fires for granular verification activity during KYC (step completed, document uploaded, verification expired, and similar), beyond the standard succeeded/failed signals.

Field	Description
`event_name`	The provider event name, e.g. step_completed, verification_expired.
`customer_email`	Customer email address.
`step_id`	Id of the verification step (may be empty).
`step_status`	Status of the step (may be empty).
`document_type`	Document being verified (may be empty).
`step_error`	JSON error object if the step errored (may be empty).
`errors`	Comma-separated list of all errors on the event.

{
  "webhook_type": "verification.event",
  "time": "2026-06-05T14:32:10+10:00",
  "event_name": "string",
  "customer_email": "jane@example.com",
  "step_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "step_status": "string",
  "document_type": "string",
  "step_error": "string",
  "errors": "string"
}

Topic AML Screening

amlscreening.completedAML

Fires when fires when an individual customer's AML screening finishes.

Field	Description
`mdb_id`	The customer's MyDataboss ID.
`aml_screening_id`	Id of the AML check.
`high_risk`	'true' / 'false'.
`risk_level`	e.g. HIGH, MEDIUM, LOW.
`match_status`	Match status from the screening provider.
`report_url`	Link to the screening report.

{
  "webhook_type": "amlscreening.completed",
  "time": "2026-06-05T14:32:10+10:00",
  "mdb_id": "A1B2C3",
  "aml_screening_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "high_risk": "false",
  "risk_level": "LOW",
  "match_status": "string",
  "report_url": "https://app.mydataboss.app/..."
}

amlscreening.failedAML

Fires when fires when an individual AML screening cannot be processed (after internal retries).

Field	Description
`mdb_id`	The customer's MyDataboss ID.
`aml_screening_id`	Id of the AML check.
`error`	Error description.

{
  "webhook_type": "amlscreening.failed",
  "time": "2026-06-05T14:32:10+10:00",
  "mdb_id": "A1B2C3",
  "aml_screening_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "error": "string"
}

kyb.amlscreening.completedAML

Fires when fires when a business entity's AML screening finishes.

Field	Description
`business_profile_id`	Id of the business / entity profile.
`aml_screening_id`	Id of the KYB AML result.
`high_risk`	'true' / 'false'.
`risk_level`	e.g. HIGH, MEDIUM, LOW.
`match_status`	Match status from the screening provider.
`report_url`	Link to the screening report.

{
  "webhook_type": "kyb.amlscreening.completed",
  "time": "2026-06-05T14:32:10+10:00",
  "business_profile_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "aml_screening_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "high_risk": "false",
  "risk_level": "LOW",
  "match_status": "string",
  "report_url": "https://app.mydataboss.app/..."
}

kyb.amlscreening.failedAML

Fires when fires when a business AML screening cannot be processed (after internal retries).

Field	Description
`entity_profile_id`	Id of the business / entity profile.
`aml_screening_id`	Id of the KYB AML result.
`error`	Error description.

{
  "webhook_type": "kyb.amlscreening.failed",
  "time": "2026-06-05T14:32:10+10:00",
  "entity_profile_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "aml_screening_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "error": "string"
}

Topic KYB (Know Your Business)

kyb.startedKYB

Fires when fires when a business entity is invited for KYB verification.

Field	Description
`business_profile_id`	Id of the business / entity profile.
`abn`	Australian Business Number.
`entity_name`	Entity name (from ABR).
`entity_type`	Entity type, e.g. Company, Sole Trader.
`entity_type_code`	Entity type code, e.g. CMP, IND.
`client_id`	Associated client id (for new-client invitations).
`invitation_type`	e.g. email.

{
  "webhook_type": "kyb.started",
  "time": "2026-06-05T14:32:10+10:00",
  "business_profile_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "abn": "51824753556",
  "entity_name": "string",
  "entity_type": "string",
  "entity_type_code": "string",
  "client_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "invitation_type": "string"
}

kyb.completedKYB

Fires when fires when KYB verification completes (all shareholders / UBOs verified).

Field	Description
`BusinessProfileId`	Id of the business / entity profile.
`ABN`	Australian Business Number.
`EntityName`	Entity name.
`LegalPersonType`	Legal person type.
`KybStatus`	Current KYB status.
`UboCompletionStatus`	UBO completion status.
`CompletedAt`	ISO-8601 completion timestamp.
`Reason`	e.g. AllShareholdersVerified.

{
  "webhook_type": "kyb.completed",
  "time": "2026-06-05T14:32:10+10:00",
  "BusinessProfileId": "string",
  "ABN": "51824753556",
  "EntityName": "string",
  "LegalPersonType": "string",
  "KybStatus": "string",
  "UboCompletionStatus": "string",
  "CompletedAt": "string",
  "Reason": "string"
}

kyb.risk_score.calculatedKYB

Fires when fires when a business entity's risk score is calculated or recalculated.

Field	Description
`business_profile_id`	Id of the business / entity profile.
`risk_rating`	Rating, e.g. high, medium, low.
`risk_score`	Numeric score.
`is_automatic_high_risk`	'false' for this event.
`trigger_event`	What triggered the calculation.
`trigger_type`	Trigger type (may be empty).
`rating_changed`	'true' / 'false'.
`previous_rating`	Prior rating (may be empty).

{
  "webhook_type": "kyb.risk_score.calculated",
  "time": "2026-06-05T14:32:10+10:00",
  "business_profile_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "risk_rating": "string",
  "risk_score": "string",
  "is_automatic_high_risk": "false",
  "trigger_event": "string",
  "trigger_type": "string",
  "rating_changed": "false",
  "previous_rating": "string"
}

kyb.risk_score.automatic_high_riskKYB

Fires when fires when a business entity is automatically flagged high-risk during risk scoring.

Field	Description
`business_profile_id`	Id of the business / entity profile.
`risk_rating`	Rating (lowercase).
`risk_score`	Numeric score.
`is_automatic_high_risk`	'true' for this event.
`trigger_event`	What triggered the calculation.
`trigger_type`	Trigger type (may be empty).
`rating_changed`	'true' / 'false'.
`previous_rating`	Prior rating (may be empty).

{
  "webhook_type": "kyb.risk_score.automatic_high_risk",
  "time": "2026-06-05T14:32:10+10:00",
  "business_profile_id": "9c1f0e21-7a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "risk_rating": "string",
  "risk_score": "string",
  "is_automatic_high_risk": "false",
  "trigger_event": "string",
  "trigger_type": "string",
  "rating_changed": "false",
  "previous_rating": "string"
}