Onboard a compliance provider

Prerequisites

• A DALP user with the admin, systemManager, or complianceManager role on the active organization.
• Credentials for the provider product you are onboarding. DALP supports Sumsub, Sumsub AML, Sumsub KYT, ComplyAdvantage, Elliptic, Jumio, Middesk, Onfido, Persona, Trulioo, and Veriff provider kinds.
• Access to the provider dashboard where the webhook destination and signing secret are configured.
• Your DALP organization's trusted issuers registry must be operational. Your DALP system administrator can confirm.

Before you open the wizard, decide which provider product you are connecting, which claim topic the provider should attest first, and which webhook authentication material the provider dashboard uses when it calls DALP back. The dapp keeps those choices together. Credential validation, claim-issuer provisioning, and the first trusted topic are created in one controlled flow.

Add the integration in DALP

A compliance provider in DALP is a provider record with one or more claim topics attached to it. The record holds the provider credentials and the on-chain claim-issuer identity. Each topic declares which on-chain claim the provider is trusted to attest. A tenant can have one active record for a provider kind, and each topic row carries the webhook token used for provider callback delivery.

https://your-platform.example.com/api/webhooks/compliance/<providerKind>/<topicWebhookId>/<topicUrlToken>

Configure the provider dashboard

The dapp shows the webhook authentication material required by the selected provider. Use the generated DALP webhook URL for the active topic as the provider callback destination. Configure the same secret, Basic Auth value, or IP allowlist you entered in DALP.

Sumsub

In the Sumsub dashboard, go to Dev space → Webhooks → Webhook manager → Create webhook. Sumsub documents the flow in its Webhook manager guide.

• Use the DALP webhook URL as the HTTP address.
• Configure the same webhook signing secret you entered in DALP.
• Sumsub sends x-payload-digest-alg and x-payload-digest headers; DALP verifies the HMAC against the raw body using the algorithm declared in the digest-alg header.

Elliptic

Configure alert webhook delivery to the DALP webhook URL in Elliptic. Elliptic documents alert webhooks in Rescreening and Alerting and API authentication in Manual Integration.

• Use the DALP webhook URL as the destination.
• Configure the same webhook signing secret you entered in DALP.
• Elliptic sends x-elliptic-signature; DALP verifies the HMAC against the raw body.
• Elliptic's native risk scores, from 0 to 10, are normalized to DALP's 0 to 100 severity range on intake. Configure the per-topic revocation severity threshold in the dapp using the named tier: Low, Medium, High, or Critical.

Initiate subject verification

DALP must initiate the verification with the provider before any inbound webhook can be matched to a DALP subject. Pass the canonical providerId from the provider list together with the topicName you are operating on so subject routes validate the active topic row, not only the oldest canonical topic.

Three routes cover the supported subject surfaces:

Hosted applicant

Use the applicant route after an identity-verification provider is active. This route covers Sumsub, Sumsub AML, Jumio, Middesk, Onfido, Persona, Trulioo, and Veriff provider records. For Sumsub KYT, register the wallet or transaction instead.

curl -X POST "https://your-platform.example.com/api/rpc/compliance.subjects.createApplicant" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "body": {
        "providerId": "11111111-1111-1111-1111-111111111111",
        "topicName": "knowYourCustomer",
        "identityAddress": "0x1111111111111111111111111111111111111111",
        "applicantHints": {
          "externalUserId": "investor-123",
          "level": "basic-kyc-level"
        }
      }
    }
  }'

Response:

{
  "data": {
    "externalId": "sumsub-applicant-id",
    "redirectUrl": "https://..."
  },
  "links": {
    "self": "/v2/compliance/subjects/create-applicant"
  }
}

DALP records the mapping between the provider's external applicant identifier and the DALP identity address before any webhook can arrive, so inbound verdicts always resolve to a known subject. The mapping is provider-scoped and serves every topic attached to the provider.

Monitoring subject

Use the wallet registration route for wallet-monitoring providers. Elliptic and Sumsub KYT use a walletAddress body:

curl -X POST "https://your-platform.example.com/api/rpc/compliance.subjects.registerWallet" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "body": {
        "providerId": "22222222-2222-2222-2222-222222222222",
        "topicName": "antiMoneyLaundering",
        "walletAddress": "0x2222222222222222222222222222222222222222"
      }
    }
  }'

Response:

{
  "data": {
    "externalId": "0x2222222222222222222222222222222222222222",
    "identityAddress": "0x3333333333333333333333333333333333333333"
  },
  "links": {
    "self": "/v2/compliance/subjects/register-wallet"
  }
}

The route resolves the wallet's on-chain identity before writing the subject mapping. Wallets that have not been registered as DALP identities are rejected with a clear error.

For ComplyAdvantage, use the same route with identityAddress and subjectHints instead of walletAddress:

{
  "input": {
    "body": {
      "providerId": "44444444-4444-4444-4444-444444444444",
      "identityAddress": "0x4444444444444444444444444444444444444444",
      "subjectHints": {
        "searchTerm": "Example Investor Ltd",
        "clientRef": "investor-123",
        "entityType": "company",
        "types": ["sanction", "warning"]
      }
    }
  }
}

DALP uses clientRef as the operator-chosen subject key and also stores the provider-assigned monitored-search id. Both keys resolve future ComplyAdvantage webhook events to the same DALP identity.

Sumsub KYT transaction

Use the transaction registration route for Sumsub KYT providers before KYT webhooks arrive:

curl -X POST "https://your-platform.example.com/api/rpc/compliance.subjects.transactions.register" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "body": {
        "providerId": "33333333-3333-3333-3333-333333333333",
        "topicName": "knowYourTransaction",
        "kytDataTxnId": "kyt-data-txn-123",
        "txn": {
          "applicantId": "sumsub-applicant-id",
          "info": {
            "address": "0x2222222222222222222222222222222222222222"
          }
        }
      }
    }
  }'

Response:

{
  "data": {
    "kytDataTxnId": "kyt-data-txn-123",
    "kytTxnId": "sumsub-kyt-txn-id",
    "identityAddress": "0x3333333333333333333333333333333333333333"
  },
  "links": {
    "self": "/v2/compliance/subjects/transactions/register"
  }
}

This route is only available for sumsub-kyt providers. DALP sends the transaction to Sumsub KYT and stores mappings for both the submitted kytDataTxnId and the provider-returned kytTxnId. When txn.info.address is present, DALP resolves that wallet to a registered on-chain identity. When the transaction has no wallet and txn.applicantId is present, DALP falls back to the existing applicant mapping for that provider.

Manage webhooks on an existing provider

Webhook management spans two state machines with different blast radii. The compliance endpoints below keep the topic webhook row and the trusted-issuer registry in sync for topic-bearing operations:

1. Compliance webhook intake config: the compliance_webhooks row decides whether DALP accepts new webhook events for the provider and topic pair. The compliance manager role owns operational pause, resume, and secret rotation.
2. On-chain TIR authorization: the trusted issuers registry claimTopics[] array decides whether the claim-issuer identity can mint claims for the topic on chain. The claim policy manager role owns this layer. Removing a topic from TIR invalidates every previously issued claim for that topic.

The webhook intake defensively checks both layers before dispatching, so drift between them (different operators, indexer lag, out-of-band TIR mutations) cannot produce silent on-chain reverts.

Add a webhook (eventual consistency across both layers)

Adds a topic to a compliance provider by updating the trusted issuers registry, then writing the compliance webhook row. This is equivalent to clicking Add topic on the provider detail page. The two writes are ordered, not a single database-and-chain transaction.

curl -X POST "https://your-platform.example.com/api/rpc/compliance.providers.webhooks.add" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "params": {
        "providerId": "11111111-1111-1111-1111-111111111111"
      },
      "body": {
        "topicName": "antiMoneyLaundering",
        "topicId": "8",
        "revocationSeverityThreshold": 60,
        "webhookSigningSecret": "provider-webhook-secret",
        "notificationChannels": []
      }
    }
  }'

Response:

{
  "data": {
    "topic": {
      "providerId": "22222222-2222-2222-2222-222222222222",
      "topicName": "antiMoneyLaundering",
      "topicId": "8",
      "webhookUrlToken": "33333333-3333-3333-3333-333333333333",
      "status": "active",
      "revocationSeverityThreshold": 60,
      "notificationChannels": [],
      "lastActivity": null,
      "createdAt": "2026-05-08T12:00:00.000Z",
      "updatedAt": "2026-05-08T12:00:00.000Z"
    }
  },
  "links": {
    "self": "/v2/compliance/providers/11111111-1111-1111-1111-111111111111/webhooks/22222222-2222-2222-2222-222222222222"
  }
}

DALP calls updateIssuerClaimTopics on the trusted issuers registry to extend the existing claim-issuer identity's topic array. DALP then writes the topic webhook row so intake accepts events for that topic. If the registry update is accepted asynchronously, DALP records the webhook as pending and Retry provisioning resumes against the existing queued transaction. If the registry update fails before acceptance, DALP records the webhook as failed when it can and Retry provisioning submits the repair attempt. If the registry update succeeds but the metadata write does not complete, the layers can temporarily diverge; retry the add flow or Retry provisioning after confirming the provider row state. No new EOA or identity is created. The new topic receives its own webhook URL token and signing secret. Permission required: claimPolicyManager; the chain enforces the same role at execution time.

Choose the webhook lifecycle action

Use topic webhook actions when one provider topic needs attention and the rest of the provider should keep working. These actions control DALP's intake channel for that topic.

They do not pause the external provider dashboard, change provider case-management state, or rotate credentials by themselves.

Pause and resume are intake-only state transitions. Only an active topic webhook can be paused, and only a paused topic webhook can be resumed. Revoke and reactivate also touch the trusted-issuer registry, so they require claim-policy authority and wallet confirmation. Secret rotation does not change the trusted-issuer registry, but it still requires wallet confirmation before DALP accepts the new signing material.

Reactivation preserves the topic webhook id and URL token. Rotate the signing secret separately if you want a fresh credential pair.

Revoke a webhook (eventual consistency across both layers)

Stop accepting new webhook events for a topic on this provider. DALP removes the topic from the issuer's trusted-issuer registry mask, then marks the webhook row as revoked. This is equivalent to clicking Revoke topic on a webhook row. The two writes are ordered, not a single database-and-chain transaction.

curl -X POST "https://your-platform.example.com/api/rpc/compliance.providers.webhooks.revoke" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "params": {
        "providerId": "11111111-1111-1111-1111-111111111111",
        "webhookId": "11111111-1111-1111-1111-111111111111"
      }
    }
  }'

The topic webhook row status changes to revoked, and webhook intake stops accepting events for this topic on this provider. If the registry update succeeds but the row update fails, repeat the revoke call for the same webhook. The retry recomputes the registry topic set and applies the revoked row transition if the webhook is still active. Permission required: claimPolicyManager.

Pause, resume, or reactivate a topic webhook

Pause and resume are the narrowest controls. Use them when the topic should stop or restart intake without changing the provider's trusted-issuer topic set.

curl -X POST "https://your-platform.example.com/api/rpc/compliance.providers.webhooks.pause" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "params": {
        "providerId": "11111111-1111-1111-1111-111111111111",
        "webhookId": "22222222-2222-2222-2222-222222222222"
      }
    }
  }'

Use the matching resume action when the topic webhook is paused. Use reactivate only after a topic webhook has been revoked and the topic should be trusted again for the same provider identity.

curl -X POST "https://your-platform.example.com/api/rpc/compliance.providers.webhooks.reactivate" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "params": {
        "providerId": "11111111-1111-1111-1111-111111111111",
        "webhookId": "22222222-2222-2222-2222-222222222222"
      }
    }
  }'

Reactivation is idempotent when the webhook row is already active. DALP returns the current topic row rather than submitting another registry mutation. It does not rotate the topic URL token or signing secret.

Invalidate every existing claim for a topic (nuclear, layer 2)

If you need to invalidate every on-chain claim that a provider's issuer minted for a topic, call the generic trusted-issuer endpoint directly. Use this only when trust in the issuer or topic has been lost. Every account with a matching claim from this provider immediately loses that claim's validity.

curl -X DELETE "https://your-platform.example.com/api/rest/v2/system/trusted-issuers/{issuerAddress}/claim-topics/{topicId}" \
  -H "Content-Type: application/json"

Use the provider's on-chain identity address and the numeric topic id. The provider detail page labels this address as Claim-issuer identity. Do not use the EOA address. The operation requires claimPolicyManager. After the registry update lands, run the compliance soft revoke above as a separate step if you also want webhook intake to stop. The two layers are independent on purpose.

Confirm trusted claims

After the provider webhook arrives and DALP authors the on-chain claim, confirm the result through the dapp's Identity view. The affected subject's claim list should include an entry for the topic. The issuer should match the claim-issuer identity address shown on the provider detail page. The architecture doc explains why the claim-issuer identity, not the EOA, is the issuer of record. The compliance module that gates transfers picks up the new claim once the indexer settles.

For monitoring providers, the provider's Monitoring tab in the dapp shows alert history with timestamp, severity, category, target topic, and whether the alert triggered claim revocation. Filter the tab to a single topic from the toolbar.

Troubleshooting

• Provisioning failed: use Retry provisioning on the provider detail page. The retry is idempotent and resumes from the last unfinished step: EOA, identity, signer key, or registry.
• Webhook signature rejected: confirm the provider dashboard authentication matches the material you entered in DALP. For HMAC providers, confirm the provider sends the expected signature header. For Jumio, confirm both the Basic Auth value and callback source IP are allowed.
• Webhook accepted but no claim appeared: confirm the subject was registered through the route that matches the provider surface: createApplicant for hosted identity or business verification, registerWallet for wallet or ComplyAdvantage monitoring, and transactions.register for Sumsub KYT transactions. Webhooks for unmapped subjects are recorded for audit but do not produce on-chain effects until the mapping is reconciled. Confirm the topic referenced by the webhook is active on the provider; events targeting a missing or revoked topic are rejected as rejected_topic_mismatch.
• Monitoring tab is empty for a Sumsub KYC provider: base Sumsub KYC applicant reviews produce issued or revoked claims, which appear in the Identity view. That provider's Monitoring tab is populated when Sumsub sends applicant-on-hold events for mapped subjects. If you only receive terminal applicantReviewed verdicts, there may be no monitoring rows to show. Sumsub AML and Sumsub KYT providers use monitoring-native event flows, so missing rows on those integrations should be investigated separately.
• Rotate the webhook signing secret: use Rotate signing secret on the provider detail page. The new secret takes effect immediately. The old secret remains valid for the configured grace window, default 15 minutes, so events the provider has already enqueued under the old secret are not lost.
• Rotate the claim signer key: see the Rotate provider claim signer key runbook. Rotation now happens on the claim-issuer identity through addKey and removeKey, and does not require any trusted issuers registry mutation.