# Provider API reference

Source: https://docs.settlemint.com/docs/developers/compliance/compliance-provider-api-reference
Reference for DALP compliance-provider endpoints, subject mapping
endpoints, webhook headers, statuses, and monitoring fields.




## Overview [#overview]

DALP exposes tenant-scoped endpoints for [Sumsub](https://docs.sumsub.com/), [ComplyAdvantage](https://docs.complyadvantage.com/), [Elliptic](https://developers.elliptic.co/), [Jumio](https://documentation.jumio.ai/docs/developer-resources/API/), [Middesk](https://docs.middesk.com/), [Onfido](https://documentation.onfido.com/api/3.1.0/), [Persona](https://docs.withpersona.com/api-introduction), [Trulioo](https://developer.trulioo.com/), and [Veriff](https://devdocs.veriff.com/apidocs/veriff-public-api-guides). Use these endpoints to configure providers, map subjects, receive webhook events, and query monitoring history.

Each compliance provider connects an external verification system to DALP claim topics, status records, and webhook delivery. You call the same API surface for all supported providers; the provider kind determines which credential shape, topic names, and webhook authentication method apply.

<Mermaid
  chart="`
flowchart TD
Provider[&#x22;Compliance provider&#x22;] --> Webhook[&#x22;DALP provider webhook&#x22;]
Integration[&#x22;Provider configuration&#x22;] --> API[&#x22;Compliance provider API&#x22;]
API --> Mapping[&#x22;Subject mappings&#x22;]
API --> Status[&#x22;Provider status records&#x22;]
API --> Topics[&#x22;Trusted claim topics&#x22;]
Webhook --> Claims[&#x22;ClaimSource issuance path&#x22;]
Mapping --> Claims
Topics --> Claims
Claims --> Assets[&#x22;Asset compliance checks&#x22;]
`"
/>

All endpoint paths below are relative to your versioned API base path. Webhook paths are relative to the platform origin.

## Provider kinds [#provider-kinds]

| Provider kind     | Supported topic names                  | Current use                                                                              |
| ----------------- | -------------------------------------- | ---------------------------------------------------------------------------------------- |
| `sumsub`          | `knowYourCustomer`                     | Identity verdicts and applicant-on-hold monitoring alerts for configured identity topics |
| `sumsub-aml`      | `antiMoneyLaundering`                  | AML / watchlist monitoring alerts on existing Sumsub applicants                          |
| `sumsub-kyt`      | `knowYourTransaction`                  | KYT transaction and wallet monitoring for both entity and wallet subjects                |
| `complyadvantage` | `antiMoneyLaundering`                  | AML and sanctions search monitoring with categorical alert severity                      |
| `elliptic`        | `antiMoneyLaundering`                  | Wallet monitoring alerts for wallet-monitoring topics                                    |
| `jumio`           | `knowYourCustomer`                     | Identity-verification verdicts                                                           |
| `middesk`         | `knowYourBusiness`                     | KYB verdicts                                                                             |
| `onfido`          | `knowYourCustomer`, `knowYourBusiness` | Workflow Studio and classic API identity-verification verdicts                           |
| `persona`         | `knowYourCustomer`, `knowYourBusiness` | Inquiry verdicts                                                                         |
| `trulioo`         | `knowYourCustomer`                     | DataVerify KYC/KYB verdicts                                                              |
| `veriff`          | `knowYourCustomer`                     | Hosted KYC session verdicts                                                              |

A provider can only be created or extended for the topic names listed for its provider kind. DALP rejects unsupported provider-topic pairs before provisioning begins. Verify that your chosen provider kind supports the topic before you call the create endpoint.

## Roles [#roles]

Compliance-provider read and operational management endpoints require one of these roles on your active organisation:

* `admin`
* `systemManager`
* `complianceManager`

To provision a provider or change trusted-issuer topic state, your account needs the claim-policy permission, exposed through the `claimPolicyManager` role. That applies to provider creation, provider revocation, adding a topic webhook, revoking a topic webhook, and reactivating a revoked topic webhook.

## Provider statuses [#provider-statuses]

| Status    | Meaning                                                          |
| --------- | ---------------------------------------------------------------- |
| `pending` | Provisioning or trusted-issuer registration is still in progress |
| `active`  | The provider can receive and process provider webhooks           |
| `paused`  | Intake is paused by an operator                                  |
| `failed`  | Provisioning failed and can be retried                           |
| `revoked` | The provider has been revoked                                    |

## Webhook lifecycle [#webhook-lifecycle]

Each provider topic has its own webhook row. A topic webhook status controls DALP intake for that one topic. It does not change the provider-level status, pause the external provider dashboard, or update the external provider's case-management state.

Operational changes affect only the selected topic webhook row. Policy changes also update the provider identity's trusted-issuer topic set.

| Operation             | Required permission                              | State change                                 | On-chain effect                                                                   |
| --------------------- | ------------------------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------- |
| Add topic webhook     | `claimPolicyManager`                             | New topic row is created                     | The provider identity is trusted for the added topic                              |
| Pause topic webhook   | `admin`, `systemManager`, or `complianceManager` | `active` -> `paused`                         | None. Intake stops for that topic                                                 |
| Resume topic webhook  | `admin`, `systemManager`, or `complianceManager` | `paused` -> `active`                         | None. Intake resumes for that topic                                               |
| Revoke topic webhook  | `claimPolicyManager`                             | Current topic webhook state -> `revoked`     | The topic is removed from the provider identity's trusted-issuer topic set        |
| Reactivate webhook    | `claimPolicyManager`                             | `revoked` -> `active`; `active` stays active | A revoked topic is added back to the provider identity's trusted-issuer topic set |
| Rotate webhook secret | `admin`, `systemManager`, or `complianceManager` | Status is unchanged                          | None. The platform stages a new verification secret for that topic webhook        |

Pause and resume are operational controls you use to start and stop intake. They keep the provider's OnchainID identity, signing EOA, and trusted-issuer registration unchanged. Revoke and reactivate are policy controls that change the topics the provider identity can attest.

Reactivation preserves the existing webhook row, webhook id, and URL token. Calling Reactivate on an already active topic webhook returns the current row without any state change. Secret rotation keeps the topic status unchanged and stages a pending secret with the requested grace window. The platform requires wallet confirmation before accepting the new signing material.

## Provider endpoints [#provider-endpoints]

| Method | Path                                                                    | Purpose                                  |
| ------ | ----------------------------------------------------------------------- | ---------------------------------------- |
| GET    | `/compliance/providers`                                                 | List tenant compliance providers         |
| POST   | `/compliance/providers`                                                 | Create and provision a provider          |
| GET    | `/compliance/providers/{providerId}`                                    | Read one provider                        |
| POST   | `/compliance/providers/validate-credentials`                            | Validate write-only provider credentials |
| POST   | `/compliance/providers/{providerId}/pause`                              | Pause intake                             |
| POST   | `/compliance/providers/{providerId}/resume`                             | Resume a paused provider                 |
| POST   | `/compliance/providers/{providerId}/retry-provisioning`                 | Retry idempotent provisioning            |
| POST   | `/compliance/providers/{providerId}/revoke`                             | Revoke the provider                      |
| POST   | `/compliance/providers/{providerId}/rotate-secret`                      | Stage a new webhook signing secret       |
| POST   | `/compliance/providers/{providerId}/promote-secret`                     | Promote the pending signing secret       |
| POST   | `/compliance/providers/{providerId}/cancel-secret-rotation`             | Discard a pending signing secret         |
| GET    | `/compliance/providers/{providerId}/health`                             | Read provider health                     |
| GET    | `/compliance/providers/{providerId}/monitoring`                         | List monitoring alerts                   |
| POST   | `/compliance/providers/{providerId}/webhooks`                           | Add another supported topic webhook      |
| POST   | `/compliance/providers/{providerId}/webhooks/{webhookId}/pause`         | Pause one topic webhook                  |
| POST   | `/compliance/providers/{providerId}/webhooks/{webhookId}/resume`        | Resume one topic webhook                 |
| POST   | `/compliance/providers/{providerId}/webhooks/{webhookId}/revoke`        | Revoke one topic webhook                 |
| POST   | `/compliance/providers/{providerId}/webhooks/{webhookId}/reactivate`    | Reactivate one revoked topic webhook     |
| POST   | `/compliance/providers/{providerId}/webhooks/{webhookId}/rotate-secret` | Stage a topic webhook signing secret     |
| POST   | `/compliance/subjects/transactions/register`                            | Register a Sumsub KYT transaction        |

## Create provider request [#create-provider-request]

`POST /compliance/providers` accepts:

| Field                  | Type                                | Notes                                                                                                                |
| ---------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `providerKind`         | Provider kind                       | Selects the provider adapter                                                                                         |
| `credentials`          | object                              | Provider-specific write-only API credentials                                                                         |
| `webhookSigningSecret` | string                              | Secret used to verify inbound provider webhooks                                                                      |
| `webhookAuthMode`      | `hmac` or `basic_auth_ip_allowlist` | Defaults to `hmac`; Jumio must be `basic_auth_ip_allowlist`                                                          |
| `webhookIpAllowlist`   | string array, optional              | Required and non-empty when the resolved mode is `basic_auth_ip_allowlist`                                           |
| `firstTopic`           | object                              | First topic configuration: `topicName`, `topicId`, optional `revocationSeverityThreshold` and `notificationChannels` |

Use `POST /compliance/providers/{providerId}/webhooks` when you need to add another supported topic to an existing multi-topic provider. The body uses the same topic fields as `firstTopic`, plus a `webhookSigningSecret`. The added topic reuses the provider identity and updates its trusted-issuer topic set.

### Create conflicts [#create-conflicts]

A `POST /compliance/providers` request is rejected when an `active` or `paused` provider already serves the same provider kind and topic in the active organisation. DALP returns public error ID `DALP-0501` for `COMPLIANCE_INVALID_STATE_TRANSITION` with HTTP 409. No second provider is created, and no credentials are stored.

A `failed` or `pending` provider does not cause a `DALP-0501` create conflict. To continue an interrupted provisioning attempt, call `POST /compliance/providers/{providerId}/retry-provisioning` on the existing `failed` or `pending` record rather than creating a new provider.

To replace a live provider for a kind and topic, you must revoke the existing provider first, then create the new one:

1. Find the live provider with `GET /compliance/providers` and note its `id`.
2. Revoke it with `POST /compliance/providers/{providerId}/revoke`.
3. Submit the `POST /compliance/providers` create request again.

A `revoked` provider does not block re-creation. Re-creating a provider for the same kind and topic after revoking the previous one returns a new provider record with its own `id`. The platform reuses the existing on-chain issuer identity and signing address rather than provisioning new ones. The revoked record stays in place for audit. To restore the revoked record itself instead of creating a new one, reactivate it at the topic-webhook level as described in [Webhook lifecycle](#webhook-lifecycle).

Webhook authentication is resolved against the selected provider. Sumsub, Elliptic, ComplyAdvantage, Sumsub AML, Sumsub KYT, Middesk, Onfido, Persona, Trulioo, and Veriff use `hmac`. Creation rejects a non-empty `webhookIpAllowlist` for those providers. Their verifiers do not consult an allowlist. Jumio supports only `basic_auth_ip_allowlist`. Sending the default `hmac` shape for Jumio is rejected, and creation requires a non-empty `webhookIpAllowlist`.

The three Sumsub provider kinds each use a distinct credential shape. The base KYC kind uses `appToken` and `secretKey`; the two monitoring kinds add `webhookSigningSecret` and `levelName`. Shapes follow in order.

Sumsub (KYC) credentials:

```json
{
  "providerKind": "sumsub",
  "credentials": {
    "appToken": "...",
    "secretKey": "..."
  }
}
```

The AML and KYT kinds extend this shape with monitoring-specific fields: both replace `appToken` with `apiToken` and add `webhookSigningSecret` and `levelName`. The AML shape:

```json
{
  "providerKind": "sumsub-aml",
  "credentials": {
    "apiToken": "...",
    "secretKey": "...",
    "webhookSigningSecret": "...",
    "levelName": "aml-monitoring-level"
  }
}
```

Sumsub KYT uses the same shape with a KYT-specific level name:

```json
{
  "providerKind": "sumsub-kyt",
  "credentials": {
    "apiToken": "...",
    "secretKey": "...",
    "webhookSigningSecret": "...",
    "levelName": "kyt-monitoring-level"
  }
}
```

Sumsub KYT supports both entity and wallet subject mapping: the applicant id anchors the entity subject, while `txn.info.address` is treated as the tenant wallet and `txn.counterparty.address` as the other side of the monitored transaction.

The remaining monitoring providers (Elliptic and ComplyAdvantage) and identity providers (Jumio onward) use the shapes below. Elliptic and ComplyAdvantage require only API credentials. For Jumio, you also supply a region and auth fields. Elliptic credentials:

```json
{
  "providerKind": "elliptic",
  "credentials": {
    "apiKey": "...",
    "apiSecret": "..."
  }
}
```

ComplyAdvantage adds a `webhookSigningSecret` to its API token credential. ComplyAdvantage credentials:

```json
{
  "providerKind": "complyadvantage",
  "credentials": {
    "apiToken": "...",
    "webhookSigningSecret": "..."
  }
}
```

Jumio credentials:

```json
{
  "providerKind": "jumio",
  "credentials": {
    "apiToken": "...",
    "apiSecret": "...",
    "region": "eu-1",
    "basicAuthCredentials": "..."
  },
  "webhookSigningSecret": "jumio-callback-basic-auth-secret",
  "webhookAuthMode": "basic_auth_ip_allowlist",
  "webhookIpAllowlist": ["203.0.113.10"]
}
```

Jumio regions are `amer-1`, `eu-1`, and `sg-1`. Jumio uses callback Basic Auth plus an IP allowlist instead of HMAC-only webhook authentication. The Basic Auth credential configured in the Jumio callback must match the provider `webhookSigningSecret`; `credentials.basicAuthCredentials` is provider credential material, not the callback verifier secret.

Middesk and the remaining identity-verification providers (Onfido, Persona, Trulioo, Veriff) each require a `webhookSigningSecret`. Use the shapes below for the provider you are configuring. Middesk credentials:

```json
{
  "providerKind": "middesk",
  "credentials": {
    "apiKey": "...",
    "webhookSigningSecret": "..."
  }
}
```

Onfido credentials (regions: `us`, `eu`, `ca`):

```json
{
  "providerKind": "onfido",
  "credentials": {
    "apiToken": "...",
    "webhookSigningSecret": "...",
    "region": "eu"
  }
}
```

Persona, Trulioo, and Veriff each include a `webhookSigningSecret` alongside their primary API credentials. Persona also requires an `inquiryTemplateId`. Persona credentials:

```json
{
  "providerKind": "persona",
  "credentials": {
    "apiToken": "...",
    "webhookSigningSecret": "...",
    "inquiryTemplateId": "itmpl_..."
  }
}
```

Trulioo and Veriff use `apiKey` and `apiSecret` in place of an `apiToken`, each paired with a `webhookSigningSecret`. Trulioo credentials, followed by Veriff credentials:

```json
{
  "providerKind": "trulioo",
  "credentials": {
    "apiKey": "...",
    "apiSecret": "...",
    "webhookSigningSecret": "..."
  }
}
```

Veriff uses the same shape with its own API key material:

```json
{
  "providerKind": "veriff",
  "credentials": {
    "apiKey": "...",
    "apiSecret": "...",
    "webhookSigningSecret": "..."
  }
}
```

## Provider response fields [#provider-response-fields]

A provider read response returns a single object with nested `topics`. List responses return the same fields plus `topicsCount`, `activeTopicsCount`, and `revokedTopicsCount`, so dashboards can show active and audit counts separately.

| Field                     | Meaning                                                  |
| ------------------------- | -------------------------------------------------------- |
| `id`                      | Provider identifier                                      |
| `providerKind`            | Provider kind                                            |
| `status`                  | Current provider status                                  |
| `statusExplanation`       | Human-readable status details                            |
| `issuerEoaAddress`        | Provider issuer EOA registered as trusted issuer         |
| `onchainIdentityAddress`  | OnchainID address for the provider issuer                |
| `providerApiKeyRef`       | Stored secret reference, not the provider API key itself |
| `webhookUrlToken`         | Provider-level URL token                                 |
| `webhookAuthMode`         | `hmac` or `basic_auth_ip_allowlist`                      |
| `webhookIpAllowlist`      | Configured source IP/CIDR allowlist, or `null`           |
| `pendingSecretExpiresAt`  | Expiry for the pending provider signing secret           |
| `lastActivity`            | Latest verdict or alert activity across the provider     |
| `lastHealthCheck`         | Last stored credential/secret health result              |
| `createdAt` / `updatedAt` | Provider timestamps                                      |

Each `topics` row includes `providerId`, `topicName`, `topicId`, its own `webhookUrlToken`, `status`, `revocationSeverityThreshold`, `notificationChannels`, `lastActivity`, `createdAt`, and `updatedAt`. Read responses include non-revoked topics by default: `pending`, `active`, `paused`, and `failed` rows. Pass `includeRevoked=true` for an audit view that adds revoked topic rows.

## Subject endpoints [#subject-endpoints]

Choose the subject endpoint that matches how your provider starts the verification flow for your subjects:

* `create-applicant` creates or starts a provider-hosted applicant, inquiry, session, or business verification for Sumsub, Sumsub AML, Jumio, Middesk, Onfido, Persona, Trulioo, and Veriff.
* `register-wallet` registers an existing DALP identity or wallet with a continuous-monitoring provider for ComplyAdvantage, Elliptic, and Sumsub KYT.
* Sumsub KYT transaction monitoring uses `register-wallet` to bind the monitored wallet or applicant to a DALP identity, then `POST /compliance/subjects/transactions/register` to register each monitored transaction.

| Method | Path                                    | Provider        | Purpose                                     |
| ------ | --------------------------------------- | --------------- | ------------------------------------------- |
| POST   | `/compliance/subjects/create-applicant` | Sumsub          | Create and map a Sumsub applicant           |
| POST   | `/compliance/subjects/create-applicant` | Sumsub AML      | Create and map a Sumsub AML applicant       |
| POST   | `/compliance/subjects/create-applicant` | Jumio           | Create and map a Jumio applicant            |
| POST   | `/compliance/subjects/create-applicant` | Middesk         | Create and map a Middesk business           |
| POST   | `/compliance/subjects/create-applicant` | Onfido          | Create and map an Onfido applicant          |
| POST   | `/compliance/subjects/create-applicant` | Persona         | Create and map a Persona inquiry            |
| POST   | `/compliance/subjects/create-applicant` | Trulioo         | Run DataVerify and map a Trulioo subject    |
| POST   | `/compliance/subjects/create-applicant` | Veriff          | Create and map a hosted Veriff session      |
| POST   | `/compliance/subjects/register-wallet`  | ComplyAdvantage | Register and map a monitored entity search  |
| POST   | `/compliance/subjects/register-wallet`  | Elliptic        | Register and map an Elliptic wallet subject |
| POST   | `/compliance/subjects/register-wallet`  | Sumsub KYT      | Register and map a monitored KYT wallet     |

`create-applicant` accepts:

| Field                                                      | Type                 | Notes                                                         |
| ---------------------------------------------------------- | -------------------- | ------------------------------------------------------------- |
| `providerId`                                               | UUID                 | Must identify an active Surface-A provider                    |
| `topicName`                                                | claim topic name     | Topic configured on the provider                              |
| `identityAddress`                                          | Ethereum address     | DALP identity address in the active system                    |
| `applicantHints.externalUserId`                            | string, optional     | External subject identifier; defaults to the identity address |
| `applicantHints.level`                                     | string, optional     | Provider workflow, level, or configuration selector           |
| `applicantHints.name` / `businessName`                     | string, Middesk only | Business name                                                 |
| `applicantHints.tin`                                       | string, Middesk only | Business tax identifier                                       |
| `applicantHints.addresses`                                 | array, Middesk only  | Business addresses                                            |
| `applicantHints.firstName` / `first_name`                  | string, Onfido only  | Applicant first name                                          |
| `applicantHints.lastName` / `last_name`                    | string, Onfido only  | Applicant last name                                           |
| `applicantHints.inquiryTemplateId` / `inquiry_template_id` | string, Persona only | Persona inquiry template override                             |
| `applicantHints.fields`                                    | object, Persona only | Persona inquiry fields                                        |
| `applicantHints.countryCode`                               | string, Trulioo only | DataVerify country code                                       |
| `applicantHints.demographics`                              | object, Trulioo only | DataVerify `DataFields.PersonInfo` input                      |
| `applicantHints.person`                                    | object, Veriff only  | Hosted session person prefill                                 |
| `applicantHints.callbackUrl`                               | string, Veriff only  | Veriff callback URL                                           |

`create-applicant` returns `externalId` and may return `redirectUrl`. When `applicantHints.level` is omitted, DALP forwards its default level value to providers that need a selector. Use that omission only when the provider tenant has a real workflow or configuration matching that exact value. The default is not a portable identifier for Jumio or Onfido.

For Jumio, pass `applicantHints.level` as the tenant's workflow definition key (the numeric key or label configured in Jumio). DALP uses `applicantHints.externalUserId`, or the identity address when omitted, as the external subject id, and may return a hosted web URL as `redirectUrl`.

Middesk requires `applicantHints.name` or `businessName`, `applicantHints.tin`, and at least one address in `applicantHints.addresses`. DALP stores Middesk `external_id`, falling back to the external subject id in the request.

For Onfido, pass `applicantHints.level` (the active workflow id), `applicantHints.firstName`, and `applicantHints.lastName`. DALP forwards optional email, phone number, redirect URLs, and locale, then maps the returned applicant id to the external subject id.

Onfido supports both `knowYourCustomer` and `knowYourBusiness` topics. Choose the correct `topicName` when creating the provider to match the subject type you intend to verify.

For Persona, pass `applicantHints.inquiryTemplateId` or configure `inquiryTemplateId` on the provider record. If both are present, the hint overrides the record value. DALP creates the inquiry and stores the returned inquiry id as the external subject id. The platform may return the hosted inquiry URL in `redirectUrl` for client-side redirect. Pass `applicantHints.fields` to pre-populate Persona inquiry fields.

For Veriff, pass `applicantHints.person` to pre-fill hosted session person data and `applicantHints.callbackUrl` when an explicit callback URL is needed. DALP stores `vendorData` as the external subject id and returns the hosted session URL in `redirectUrl`.

Trulioo requires `applicantHints.countryCode` and `applicantHints.demographics`. DALP forwards the demographics object to DataVerify as `DataFields.PersonInfo` and stores the returned `CustomerReferenceID` as the external subject id. Trulioo does not return a hosted redirect URL. Verification happens on the Trulioo side with no client-side redirect.

`register-wallet` accepts an Elliptic wallet mapping, a Sumsub KYT wallet mapping, or a ComplyAdvantage entity-search mapping:

| Field                     | Type                   | Notes                                                                   |
| ------------------------- | ---------------------- | ----------------------------------------------------------------------- |
| `providerId`              | UUID                   | Must identify an active Surface-B provider                              |
| `topicName`               | claim topic name       | Topic configured on the provider                                        |
| `walletAddress`           | Ethereum address       | Elliptic and Sumsub KYT; wallet already registered to a DALP identity   |
| `identityAddress`         | Ethereum address       | ComplyAdvantage only; DALP identity to bind to the search               |
| `subjectHints.searchTerm` | string                 | ComplyAdvantage search term                                             |
| `subjectHints.clientRef`  | string, optional       | ComplyAdvantage client reference; defaults to `identityAddress`         |
| `subjectHints.entityType` | string, optional       | ComplyAdvantage entity type; defaults to `person`                       |
| `subjectHints.types`      | string array, optional | ComplyAdvantage screening list types; defaults to `sanction`, `warning` |

`register-wallet` returns `externalId` and the resolved `identityAddress`. For Sumsub KYT, the returned `externalId` is the provider applicant id that transaction registration can later use when a transaction has no wallet address.

## Webhook paths [#webhook-paths]

Provider dashboards send webhook events to:

```text
/api/webhooks/compliance/<provider>/<webhookId>/<urlToken>
```

Build each webhook URL from the specific topic row that should receive the provider delivery. Use `topics[].providerId` as `<webhookId>` and `topics[].webhookUrlToken` as `<urlToken>`. For the first topic, those values match the provider-level webhook row. Additional topics each have their own row identifier and token.

Current provider path segments are:

* `sumsub`
* `sumsub-aml`
* `sumsub-kyt`
* `complyadvantage`
* `elliptic`
* `jumio`
* `middesk`
* `onfido`
* `persona`
* `trulioo`
* `veriff`

The request body limit is 64 KiB.

## Webhook signatures [#webhook-signatures]

| Provider        | Headers                                    | Accepted digest                                                        |
| --------------- | ------------------------------------------ | ---------------------------------------------------------------------- |
| Sumsub          | `x-payload-digest`, `x-payload-digest-alg` | `HMAC_SHA1_HEX`, `HMAC_SHA256_HEX`, or `HMAC_SHA512_HEX` over raw body |
| ComplyAdvantage | `x-complyadvantage-signature`              | HMAC-SHA256 hex over raw body                                          |
| Elliptic        | `x-elliptic-signature`                     | HMAC-SHA256 hex over raw body, with optional `sha256=` prefix          |
| Jumio           | `Authorization`                            | Basic Auth credentials plus configured source IP allowlist             |
| Middesk         | `x-middesk-signature-256`                  | HMAC-SHA256 hex over raw body                                          |
| Onfido          | `x-sha2-signature`                         | HMAC-SHA256 hex over raw body                                          |
| Persona         | `persona-signature`                        | HMAC-SHA256 hex over `${timestamp}.${rawBody}`                         |
| Trulioo         | `x-trulioo-signature`                      | HMAC-SHA256 hex over raw body                                          |
| Veriff          | `x-hmac-signature`                         | HMAC-SHA256 hex over raw body                                          |

If Sumsub omits `x-payload-digest-alg`, DALP uses `HMAC_SHA256_HEX`. Persona accepts space-separated signature sets during key rotation.

Trulioo DataVerify webhooks prefer the top-level `TransactionId` as the provider event id. Legacy deliveries without that stable id use a lower-trust composite fallback: SHA-256 over `(TransactionId, RecordStatus, body_hash)`, where `body_hash` is the SHA-256 hex digest of the raw body.

ComplyAdvantage webhooks prefer the top-level `id` as the provider event id. Legacy deliveries without that stable id use a composite fallback: SHA-256 over `(search_id, created_at)`.

## Webhook processing outcomes [#webhook-processing-outcomes]

DALP resolves the topic webhook before reading the request body or verifying the provider signature. Paused and failed webhooks return their public error ID without storing a provider event. The named outcome in each row is the DALP classification behind the public response your provider receives.

| Condition                                          | Behaviour                                                                                                                        |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Topic webhook is paused                            | Request returns public error ID `DALP-0491` with HTTP 404 for `COMPLIANCE_PROVIDER_PAUSED`; no event is stored                   |
| Topic webhook is failed                            | Request returns public error ID `DALP-0492` with HTTP 409 for `COMPLIANCE_PROVIDER_FAILED`; no event is stored                   |
| Body exceeds 64 KiB                                | Request returns `{ status: "request_too_large" }` with HTTP 413; no event is stored and retrying the same body will keep failing |
| Signature invalid                                  | Request is rejected                                                                                                              |
| New event is outside the five-minute replay window | Request is rejected                                                                                                              |
| Duplicate completed event                          | Event is treated as replayed                                                                                                     |
| Retryable claim processing failure                 | Request returns retry behaviour so the provider can resend                                                                       |
| Subject is unmapped                                | Event is recorded for audit, but no on-chain claim effect occurs                                                                 |

Use pause to stop DALP from accepting events for a topic without revoking the provider's trusted-issuer registration. If intake returns `DALP-0491` for `COMPLIANCE_PROVIDER_PAUSED`, resume the topic webhook before asking the external provider to resend events. If intake returns `DALP-0492` for `COMPLIANCE_PROVIDER_FAILED`, repair or reprovision the provider before retrying webhook processing.

## Monitoring fields [#monitoring-fields]

The monitoring endpoint returns paginated rows. Each row includes:

| Field             | Meaning                                                    |
| ----------------- | ---------------------------------------------------------- |
| `id`              | Monitoring row ID                                          |
| `providerEventId` | Provider event identifier                                  |
| `subjectAddress`  | DALP subject address when resolved                         |
| `topicName`       | Claim topic when available                                 |
| `severity`        | Normalised severity from `0` through `100`, when available |
| `outcome`         | Processing outcome                                         |
| `rawPayload`      | Original provider payload retained for audit               |
| `processedAt`     | Processing timestamp when completed                        |
| `createdAt`       | Row creation timestamp                                     |

## See also [#see-also]

* [Onboard a compliance provider](/docs/developers/compliance/onboarding-a-provider)
* [Map compliance-provider subjects](/docs/developers/compliance/compliance-provider-subjects)
* [How compliance provider intake works](/docs/architects/integrations/compliance-providers)