SDKs and External Integration Surface - Python SDK Resources, Shared Errors, and Webhook Helpers
Overview
The Python SDK is the typed integration layer for Lita’s regional API surface. It gives application code a small set of resource facades for the consent lifecycle, evidence retrieval, async feature computation, and job status polling, while mapping the API payloads into explicit Python models and literal state values.
This surface mirrors the same REST semantics exposed by the Node and Java SDKs: consent creation uses the same request fields, evidence is retrieved by evidence_ref, async work is started through features.compute and tracked through status.get, and webhook events are validated with the same HMAC-SHA256 signature scheme. The SDK also centralizes API error handling through a shared exception hierarchy and provides a webhook verification helper for inbound event handlers.
Architecture Overview
flowchart TB
subgraph AppCode[Consumer Application]
App[Application code]
WebhookHandler[Webhook endpoint]
end
subgraph PythonSDK[Python SDK Surface]
ConsentsResource[ConsentsResource]
EvidenceResource[EvidenceResource]
FeaturesResource[FeaturesResource]
StatusResource[StatusResource]
WebhooksHelper[construct_event]
ErrorTypes[LitaError hierarchy]
SharedTypes[Type aliases and models]
end
subgraph LitaAPI[Lita API]
ConsentAPI[Consent endpoints]
EvidenceAPI[Evidence endpoint]
FeaturesAPI[Feature compute endpoint]
StatusAPI[Job status endpoint]
WebhookDelivery[Webhook delivery]
end
App --> ConsentsResource
App --> EvidenceResource
App --> FeaturesResource
App --> StatusResource
App --> WebhooksHelper
ConsentsResource --> ConsentAPI
EvidenceResource --> EvidenceAPI
FeaturesResource --> FeaturesAPI
StatusResource --> StatusAPI
LitaAPI --> WebhookHandler
WebhookHandler --> WebhooksHelper
ConsentsResource -.-> SharedTypes
EvidenceResource -.-> SharedTypes
FeaturesResource -.-> SharedTypes
StatusResource -.-> SharedTypes
WebhooksHelper -.-> SharedTypes
ConsentsResource -.-> ErrorTypes
EvidenceResource -.-> ErrorTypes
FeaturesResource -.-> ErrorTypes
StatusResource -.-> ErrorTypes
Packaging and Runtime Dependencies
sdks/python/pyproject.toml
[!NOTE] The Python SDK keeps the same resource boundaries as the other official SDKs, but it uses Python naming conventions:
construct_eventin Python corresponds toconstructEventin Node and Java.
The Python package is published as lita-python and targets Python 3.9 or newer. Runtime and development dependencies are declared centrally in pyproject.toml.
| Setting | Value | Responsibility |
|---|---|---|
project.name |
lita-python |
Package identity for distribution |
project.version |
1.2.0 |
SDK release version |
project.description |
Official Lita Python SDK |
Public package description |
project.license.text |
MIT |
License declaration |
project.requires-python |
>=3.9 |
Supported interpreter range |
project.dependencies |
httpx>=0.27.0 |
HTTP transport dependency |
project.optional-dependencies.dev |
pytest, pytest-asyncio, mypy, ruff, respx |
Development and test tooling |
tool.setuptools.packages.find.include |
lita* |
Package discovery scope |
tool.mypy.strict |
true |
Strict type checking |
tool.mypy.python_version |
3.9 |
Type-check target |
tool.ruff.line-length |
100 |
Lint formatting constraint |
build-system.requires |
setuptools>=68, wheel |
Build requirements |
build-system.build-backend |
setuptools.backends.legacy:build |
Packaging backend |
Shared Type System
Type Aliases
The SDK uses literal-backed state tokens so callers can branch on API state without parsing free-form strings.
| Alias | Values | Used By |
|---|---|---|
Region |
us, jp |
Regional routing and webhook payloads |
ConsentPurpose |
RENTAL_SCREENING, LENDING_UNDERWRITING, EMPLOYMENT_SCREENING, ACCOUNT_OPENING |
Consent creation |
DataCategory |
transactions, income, payment_behavior, obligations, employment |
Consent creation |
ConsentStatus |
PENDING, ACTIVE, REVOKED, EXPIRED |
Consent lifecycle responses |
JobStatus |
PROCESSING, COMPLETE, FAILED |
Async feature job status |
ScoreDecision |
APPROVE, REVIEW, DECLINE, INSUFFICIENT_DATA |
Score responses |
KycStatus |
PASSED, REVIEW, FAILED, PENDING |
KYC responses and webhook payloads |
DelinquencyBucket |
CURRENT, 30_DPD, 60_DPD, 90_PLUS_DPD, CHARGE_OFF, WRITE_OFF |
Evidence snapshots |
WebhookEventType |
consent.activated, consent.expired, consent.revoked, data.updated, features.computed, score.completed, kyc.updated |
Webhook event routing |
Consent (sdks/python/lita/types.py)
Represents the consent record returned by create, get, and revoke operations.
| Property | Type | Description |
|---|---|---|
consent_id |
str |
Consent identifier |
status |
ConsentStatus |
Current consent state |
applicant_id |
str |
Applicant identifier supplied at creation |
purpose |
ConsentPurpose |
Declared consent purpose |
expires_at |
str |
Expiration timestamp |
redirect_url |
Optional[str] |
Redirect target returned during creation |
created_at |
Optional[str] |
Creation timestamp |
activated_at |
Optional[str] |
Activation timestamp |
revoked_at |
Optional[str] |
Revocation timestamp |
connections |
List[Connection] |
Linked provider connections |
Connection (sdks/python/lita/types.py)
Returned inside Consent.connections.
| Property | Type | Description |
|---|---|---|
connection_id |
str |
Provider connection identifier |
provider |
str |
Provider name |
status |
str |
Provider connection status string |
KycCheckDetail (sdks/python/lita/types.py)
Represents a single KYC or AML check result inside KycResult.checks.
| Property | Type | Description |
|---|---|---|
status |
KycStatus |
Check outcome |
method |
Optional[str] |
Verification method name |
lists_screened |
Optional[List[str]] |
Lists screened during the check |
risk_level |
Optional[str] |
Risk classification returned by the API |
KycResult (sdks/python/lita/types.py)
Returned by ConsentsResource.get_kyc.
| Property | Type | Description |
|---|---|---|
consent_id |
str |
Consent identifier tied to the compliance result |
status |
KycStatus |
Overall compliance outcome |
checks |
Dict[str, KycCheckDetail] |
Named per-check results |
completed_at |
str |
Completion timestamp |
ComputeFeaturesResponse (sdks/python/lita/types.py)
Returned by FeaturesResource.compute.
| Property | Type | Description |
|---|---|---|
job_id |
str |
Async job identifier |
status |
JobStatus |
Current job state |
consent_id |
str |
Consent processed by the job |
estimated_completion_ms |
int |
Estimated completion time in milliseconds |
JobStatusResponse (sdks/python/lita/types.py)
Returned by StatusResource.get.
| Property | Type | Description |
|---|---|---|
job_id |
str |
Async job identifier |
status |
JobStatus |
Current job state |
consent_id |
str |
Consent associated with the job |
completed_at |
Optional[str] |
Completion timestamp when available |
error |
Optional[Dict[str, str]] |
Error payload when the job fails |
Score (sdks/python/lita/types.py)
Returned by ConsentsResource.get_score.
| Property | Type | Description |
|---|---|---|
consent_id |
str |
Consent identifier |
applicant_id |
str |
Applicant identifier |
score |
int |
Computed score value |
score_range |
ScoreRange |
Score bounds returned by the API |
decision |
ScoreDecision |
Decision derived from the score |
score_factors |
List[str] |
Factors used in the score explanation |
evidence_ref |
str |
Evidence snapshot reference |
scored_at |
str |
Score timestamp |
model_version |
str |
Model version used for scoring |
EvidenceSnapshot (sdks/python/lita/types.py)
Returned by EvidenceResource.get.
| Property | Type | Description |
|---|---|---|
evidence_ref |
str |
Immutable evidence reference |
consent_id |
str |
Consent identifier |
applicant_id |
str |
Applicant identifier |
snapshot_version |
str |
Snapshot schema version |
created_at |
str |
Snapshot creation timestamp |
score_inputs |
Dict[str, Any] |
Score input payload returned by the API |
kyc_result |
Dict[str, Any] |
KYC payload returned by the API |
delinquency_bucket |
DelinquencyBucket |
Final delinquency classification |
TransactionListResponse (sdks/python/lita/types.py)
Returned by ConsentsResource.list_transactions.
| Property | Type | Description |
|---|---|---|
data |
List[Transaction] |
Paginated transaction records |
next_cursor |
Optional[str] |
Cursor for the next page |
total_count |
int |
Total count returned by the API |
WebhookEvent (sdks/python/lita/types.py)
Returned by construct_event.
| Property | Type | Description |
|---|---|---|
event_id |
str |
Event identifier |
event_type |
WebhookEventType |
Event kind |
created_at |
str |
Event timestamp |
region |
Region |
Region that emitted the event |
data |
Dict[str, Any] |
Event payload |
Error Hierarchy
LitaError (sdks/python/lita/errors.py)
Base exception for API failures.
| Property | Type | Description |
|---|---|---|
status |
int |
HTTP status code |
code |
str |
Machine-readable error code |
request_id |
str |
Request correlation identifier |
retryable |
bool |
Retryability flag returned by the API |
Public methods
| Method | Description |
|---|---|
__init__ |
Builds the exception from a status code and an error response body |
__repr__ |
Returns a compact string representation containing the status and code |
LitaAuthError (sdks/python/lita/errors.py)
Specializes LitaError for 401 and 403 responses. It does not add new fields.
LitaNotFoundError (sdks/python/lita/errors.py)
Specializes LitaError for 404 responses. It does not add new fields.
LitaRateLimitError (sdks/python/lita/errors.py)
Specializes LitaError for 429 responses and exposes retry metadata.
| Property | Type | Description |
|---|---|---|
retry_after |
Optional[int] |
Retry delay when the API returns rate-limit guidance |
LitaWebhookSignatureError (sdks/python/lita/errors.py)
Raised when webhook signature verification fails. The exception message is fixed to:
Webhook signature verification failed. Ensure you are using the correct webhook secret.
Resource Facades
ConsentsResource (sdks/python/lita/resources/consents.py)
This resource wraps the consent lifecycle, score retrieval, transactions, and KYC inspection. Its methods call the injected HTTP client directly and convert the raw JSON into typed Python objects.
Constructor Dependency
| Type | Description |
|---|---|
HttpClient |
Transport client used for all consent-related requests |
Public Methods
| Method | Description |
|---|---|
create |
Creates a consent from applicant_id, purpose, data_categories, and expires_in_days, then returns Consent |
get |
Fetches the current consent state by consent ID and returns Consent |
revoke |
Revokes a consent by consent ID and returns Consent |
get_score |
Retrieves the computed score for a consent and returns Score |
list_transactions |
Lists paginated transactions for a consent and returns TransactionListResponse |
get_kyc |
Retrieves KYC and AML results for a consent and returns KycResult |
Create Consent
{
"title": "Create Consent",
"description": "Creates a consent and returns the redirect URL",
"method": "POST",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents",
"headers": [
{
"key": "Authorization",
"value": "Bearer <apiKey>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"applicant_id\": \"app_demo_001\",\n \"purpose\": \"LENDING_UNDERWRITING\",\n \"data_categories\": [\n \"transactions\",\n \"income\",\n \"payment_behavior\"\n ],\n \"expires_in_days\": 30\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J2ABCDEF1234567890\",\n \"status\": \"PENDING\",\n \"applicant_id\": \"app_demo_001\",\n \"purpose\": \"LENDING_UNDERWRITING\",\n \"expires_at\": \"2026-04-30T12:00:00Z\",\n \"redirect_url\": \"https://connect.joinlita.com/consents/con_01J2ABCDEF1234567890/redirect\",\n \"created_at\": \"2026-03-31T12:00:00Z\",\n \"activated_at\": null,\n \"revoked_at\": null,\n \"connections\": []\n}"
}
}
}
Get Consent
{
"title": "Get Consent",
"description": "Fetches the current consent state",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consent_id}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <apiKey>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "con_01J2ABCDEF1234567890",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J2ABCDEF1234567890\",\n \"status\": \"ACTIVE\",\n \"applicant_id\": \"app_demo_001\",\n \"purpose\": \"LENDING_UNDERWRITING\",\n \"expires_at\": \"2026-04-30T12:00:00Z\",\n \"redirect_url\": \"https://connect.joinlita.com/consents/con_01J2ABCDEF1234567890/redirect\",\n \"created_at\": \"2026-03-31T12:00:00Z\",\n \"activated_at\": \"2026-03-31T12:03:00Z\",\n \"revoked_at\": null,\n \"connections\": [\n {\n \"connection_id\": \"conn_01J2XYZ9876543210\",\n \"provider\": \"bank_one\",\n \"status\": \"ACTIVE\"\n }\n ]\n}"
}
}
}
Revoke Consent
{
"title": "Revoke Consent",
"description": "Revokes an active consent",
"method": "DELETE",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consent_id}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <apiKey>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "con_01J2ABCDEF1234567890",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J2ABCDEF1234567890\",\n \"status\": \"REVOKED\",\n \"applicant_id\": \"app_demo_001\",\n \"purpose\": \"LENDING_UNDERWRITING\",\n \"expires_at\": \"2026-04-30T12:00:00Z\",\n \"redirect_url\": \"https://connect.joinlita.com/consents/con_01J2ABCDEF1234567890/redirect\",\n \"created_at\": \"2026-03-31T12:00:00Z\",\n \"activated_at\": \"2026-03-31T12:03:00Z\",\n \"revoked_at\": \"2026-03-31T12:20:00Z\",\n \"connections\": [\n {\n \"connection_id\": \"conn_01J2XYZ9876543210\",\n \"provider\": \"bank_one\",\n \"status\": \"CLOSED\"\n }\n ]\n}"
}
}
}
Get Consent Score
{
"title": "Get Consent Score",
"description": "Retrieves the computed score for a consent",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consent_id}/score",
"headers": [
{
"key": "Authorization",
"value": "Bearer <apiKey>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "con_01J2ABCDEF1234567890",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J2ABCDEF1234567890\",\n \"applicant_id\": \"app_demo_001\",\n \"score\": 742,\n \"score_range\": {\n \"min\": 300,\n \"max\": 850\n },\n \"decision\": \"APPROVE\",\n \"score_factors\": [\n \"payment_behavior\",\n \"income_stability\",\n \"low_obligations\"\n ],\n \"evidence_ref\": \"evd_01J2EVIDENCE123456\",\n \"scored_at\": \"2026-03-31T12:15:00Z\",\n \"model_version\": \"score-v3.2.0\"\n}"
}
}
}
List Transactions
{
"title": "List Transactions",
"description": "Lists paginated transactions for a consent",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consent_id}/data/transactions",
"headers": [
{
"key": "Authorization",
"value": "Bearer <apiKey>",
"required": true
}
],
"queryParams": [
{
"key": "limit",
"value": "25",
"required": false
},
{
"key": "cursor",
"value": "cursor_01J2NEXTPAGE",
"required": false
},
{
"key": "from_date",
"value": "2026-01-01",
"required": false
},
{
"key": "to_date",
"value": "2026-03-31",
"required": false
}
],
"pathParams": [
{
"key": "consent_id",
"value": "con_01J2ABCDEF1234567890",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"data\": [\n {\n \"transaction_id\": \"txn_01J2TXN0001\",\n \"date\": \"2026-03-29\",\n \"amount\": -42.35,\n \"currency\": \"USD\",\n \"description\": \"Grocery Store\",\n \"category\": \"groceries\",\n \"type\": \"DEBIT\"\n }\n ],\n \"next_cursor\": \"cursor_01J2NEXTPAGE\",\n \"total_count\": 128\n}"
}
}
}
Get KYC Results
{
"title": "Get KYC Results",
"description": "Retrieves KYC and AML compliance check results for a consent",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/consents/{consent_id}/kyc",
"headers": [
{
"key": "Authorization",
"value": "Bearer <apiKey>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "consent_id",
"value": "con_01J2ABCDEF1234567890",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"consent_id\": \"con_01J2ABCDEF1234567890\",\n \"status\": \"PASSED\",\n \"checks\": {\n \"identity\": {\n \"status\": \"PASSED\",\n \"method\": \"document_and_selfie\",\n \"lists_screened\": [\n \"government_id\"\n ],\n \"risk_level\": \"low\"\n },\n \"sanctions\": {\n \"status\": \"PASSED\",\n \"method\": \"watchlist_screening\",\n \"lists_screened\": [\n \"sanctions\",\n \"pep\"\n ],\n \"risk_level\": \"low\"\n }\n },\n \"completed_at\": \"2026-03-31T12:05:00Z\"\n}"
}
}
}
EvidenceResource (sdks/python/lita/resources/evidence.py)
[!NOTE]
revokeparses the response back into the fullConsentmodel, so the Python SDK expects the revoke response to contain the same core consent fields used bycreateandget.
This resource retrieves immutable evidence snapshots for audit trails, adverse action notices, and regulatory responses. The docstring explicitly states that snapshots are retained for 7 years from creation.
Constructor Dependency
| Type | Description |
|---|---|
HttpClient |
Transport client used for evidence snapshot retrieval |
Public Methods
| Method | Description |
|---|---|
get |
Retrieves an immutable evidence snapshot by evidence_ref and returns EvidenceSnapshot |
Get Evidence Snapshot
{
"title": "Get Evidence Snapshot",
"description": "Retrieves an immutable evidence snapshot",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/evidence/{evidence_ref}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <apiKey>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "evidence_ref",
"value": "evd_01J2EVIDENCE123456",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"evidence_ref\": \"evd_01J2EVIDENCE123456\",\n \"consent_id\": \"con_01J2ABCDEF1234567890\",\n \"applicant_id\": \"app_demo_001\",\n \"snapshot_version\": \"1\",\n \"created_at\": \"2026-03-31T12:05:00Z\",\n \"score_inputs\": {\n \"payment_behavior\": {\n \"payments_observed\": 18,\n \"avg_payment_delay_days\": 2,\n \"late_payment_count_30d_plus\": 0\n },\n \"income\": {\n \"monthly_net_income\": 6200,\n \"income_stability_score\": 91\n },\n \"obligations\": {\n \"total_monthly_obligations\": 1450,\n \"obligation_to_income_ratio\": 0.23\n }\n },\n \"kyc_result\": {\n \"status\": \"PASSED\",\n \"checks\": [\n \"identity\",\n \"sanctions\"\n ]\n },\n \"delinquency_bucket\": \"CURRENT\"\n}"
}
}
}
FeaturesResource (sdks/python/lita/resources/features.py)
This resource starts the async feature computation pipeline and returns the job metadata immediately.
Constructor Dependency
| Type | Description |
|---|---|
HttpClient |
Transport client used to start feature jobs |
Public Methods
| Method | Description |
|---|---|
compute |
Starts feature computation for an active consent and returns ComputeFeaturesResponse |
Compute Features
{
"title": "Compute Features",
"description": "Triggers the feature computation pipeline",
"method": "POST",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/features/compute",
"headers": [
{
"key": "Authorization",
"value": "Bearer <apiKey>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"consent_id\": \"con_01J2ABCDEF1234567890\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"job_id\": \"job_01J2FEATURE123456\",\n \"status\": \"PROCESSING\",\n \"consent_id\": \"con_01J2ABCDEF1234567890\",\n \"estimated_completion_ms\": 4500\n}"
}
}
}
StatusResource (sdks/python/lita/resources/status.py)
[!NOTE] The
computedocstring marks the operation as asynchronous and directs callers toward thescore.completedwebhook rather than polling whenever possible.
This resource polls async job status for a job_id returned by FeaturesResource.compute.
Constructor Dependency
| Type | Description |
|---|---|
HttpClient |
Transport client used for job status polling |
Public Methods
| Method | Description |
|---|---|
get |
Polls an async job by job ID and returns JobStatusResponse |
Get Job Status
{
"title": "Get Job Status",
"description": "Polls the status of an async processing job",
"method": "GET",
"baseUrl": "<LitaApiBaseUrl>",
"endpoint": "/{region}/status/{job_id}",
"headers": [
{
"key": "Authorization",
"value": "Bearer <apiKey>",
"required": true
}
],
"queryParams": [],
"pathParams": [
{
"key": "job_id",
"value": "job_01J2FEATURE123456",
"required": true
}
],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"job_id\": \"job_01J2FEATURE123456\",\n \"status\": \"COMPLETE\",\n \"consent_id\": \"con_01J2ABCDEF1234567890\",\n \"completed_at\": \"2026-03-31T12:10:30Z\",\n \"error\": null\n}"
}
}
}
Webhook Helpers
construct_event (sdks/python/lita/webhooks.py)
[!NOTE] The docstring explicitly says polling is rate-limited to 2 requests per second per job ID and recommends webhooks when available.
The webhook helper verifies the X-Lita-Signature header and returns a parsed WebhookEvent. It accepts the raw request body as bytes or str, computes an HMAC-SHA256 digest using the shared secret, compares the result in constant time, and only then parses the JSON payload.
Parameters
| Parameter | Type | Description |
|---|---|---|
raw_body |
Union[bytes, str] |
Raw request body; string values are encoded as UTF-8 before verification |
signature |
str |
Value of the X-Lita-Signature header |
secret |
str |
Webhook signing secret from the Lita dashboard |
Returns
| Return type | Description |
|---|---|
WebhookEvent |
Parsed webhook event object |
Failure mode
| Condition | Exception |
|---|---|
| Signature mismatch | LitaWebhookSignatureError |
from lita.webhooks import construct_event
from lita.errors import LitaWebhookSignatureError
try:
event = construct_event(raw_body, signature, secret)
except LitaWebhookSignatureError:
# Reject the request
...
Webhook Verification Flow
sequenceDiagram
participant LitaAPI as Lita API
participant App as Webhook endpoint
participant Helper as construct_event
participant Types as WebhookEvent model
LitaAPI->>App: POST webhook payload and signature
App->>Helper: construct_event raw body signature secret
Helper->>Helper: Encode body if needed
Helper->>Helper: Compute HMAC SHA256
Helper->>Helper: Compare signature in constant time
alt Signature mismatch
Helper-->>App: LitaWebhookSignatureError
else Signature valid
Helper->>Types: Build WebhookEvent
Types-->>Helper: WebhookEvent
Helper-->>App: Parsed event
end
Feature Flows
Consent Creation and Score Retrieval
A typical consent flow starts with ConsentsResource.create, then uses the returned consent ID later for consent inspection and score retrieval.
sequenceDiagram
participant App as Application
participant CR as ConsentsResource
participant HC as HttpClient
participant API as Lita API
App->>CR: create
CR->>HC: post consents
HC->>API: POST /{region}/consents
API-->>HC: Consent JSON
HC-->>CR: Consent
CR-->>App: Consent with redirect_url
App->>CR: get_score
CR->>HC: get consents consent score
HC->>API: GET /{region}/consents/{consent_id}/score
API-->>HC: Score JSON
HC-->>CR: Score
CR-->>App: Score and decision
Evidence Snapshot Retrieval for Audit Use
Evidence snapshots are retrieved by reference and are intended for audit and regulatory use cases.
sequenceDiagram
participant App as Application
participant ER as EvidenceResource
participant HC as HttpClient
participant API as Lita API
App->>ER: get
ER->>HC: get evidence ref
HC->>API: GET /{region}/evidence/{evidence_ref}
API-->>HC: EvidenceSnapshot JSON
HC-->>ER: EvidenceSnapshot
ER-->>App: Immutable snapshot for audit use
Async Feature Computation and Status Polling
FeaturesResource.compute starts the job and returns immediately. The job is then observed through StatusResource.get or completed through webhook delivery.
sequenceDiagram
participant App as Application
participant FR as FeaturesResource
participant SR as StatusResource
participant HC as HttpClient
participant API as Lita API
App->>FR: compute
FR->>HC: post features compute
HC->>API: POST /{region}/features/compute
API-->>HC: ComputeFeaturesResponse
HC-->>FR: Job metadata
FR-->>App: job_id and estimated_completion_ms
App->>SR: get
SR->>HC: get status job_id
HC->>API: GET /{region}/status/{job_id}
API-->>HC: JobStatusResponse
HC-->>SR: JobStatusResponse
SR-->>App: status update
State Management
The SDK models server-side state as literal values and response objects instead of mutable client-side state.
| State family | Values | Where it appears |
|---|---|---|
ConsentStatus |
PENDING, ACTIVE, REVOKED, EXPIRED |
Consent.status |
JobStatus |
PROCESSING, COMPLETE, FAILED |
ComputeFeaturesResponse.status, JobStatusResponse.status |
KycStatus |
PASSED, REVIEW, FAILED, PENDING |
KycCheckDetail.status, KycResult.status, webhook payloads |
ScoreDecision |
APPROVE, REVIEW, DECLINE, INSUFFICIENT_DATA |
Score.decision |
WebhookEventType |
consent.activated, consent.expired, consent.revoked, data.updated, features.computed, score.completed, kyc.updated |
WebhookEvent.event_type |
DelinquencyBucket |
CURRENT, 30_DPD, 60_DPD, 90_PLUS_DPD, CHARGE_OFF, WRITE_OFF |
EvidenceSnapshot.delinquency_bucket |
Region |
us, jp |
URL routing and webhook payloads |
ConsentPurpose |
RENTAL_SCREENING, LENDING_UNDERWRITING, EMPLOYMENT_SCREENING, ACCOUNT_OPENING |
Consent creation |
DataCategory |
transactions, income, payment_behavior, obligations, employment |
Consent creation |
Integration Points
- Lita API regional surfaces: resource methods are routed under
/{region}/..., matching the same regional split used by the other official SDKs. - Consent lifecycle:
create,get,revoke,get_score,list_transactions, andget_kycall operate on the same consent record. - Evidence and audit workflows:
EvidenceResource.getconsumes theevidence_refreturned by scoring flows. - Async job workflows:
FeaturesResource.computestarts work,StatusResource.getpolls it, and webhook consumers can validate completion events throughconstruct_event. - Webhook receivers: inbound handlers use the shared webhook signature scheme and parse into
WebhookEvent. - Shared error envelope: the SDK’s
LitaErrorstructure is aligned with the API’s nestederrorpayload shape. - Cross-SDK parity: the Python surface mirrors the same resource set and payload semantics exposed by Node and Java.
Error Handling
The Python SDK models HTTP and webhook failures as typed exceptions.
LitaErrorreads the nestederrorobject from the API response body.LitaAuthErrorrepresents authentication and authorization failures.LitaNotFoundErrorrepresents missing resources.LitaRateLimitErrorcaptures server-provided retry timing throughretry_after.LitaWebhookSignatureErroris raised when webhook verification fails.
from lita.errors import LitaError, LitaRateLimitError, LitaWebhookSignatureError
from lita.webhooks import construct_event
try:
consent = client.consents.create(
applicant_id="app_demo_001",
purpose="LENDING_UNDERWRITING",
data_categories=["transactions", "income", "payment_behavior"],
expires_in_days=30,
)
except LitaRateLimitError as exc:
print(exc.status, exc.code, exc.retry_after)
except LitaError as exc:
print(exc.status, exc.code, exc.request_id, exc.retryable)
try:
event = construct_event(raw_body, signature, secret)
except LitaWebhookSignatureError:
print("Reject webhook")
Testing Considerations
[!NOTE]
LitaErrorfalls back toUnknown error,unknown, an empty request ID, andFalseif those fields are absent from the API error body.
- Use
respxto stub thehttpxtransport and assert the exact path fragments used by each resource method. - Validate that consent creation sends
applicant_id,purpose,data_categories, andexpires_in_days. - Verify that
EvidenceResource.getmaps the snapshot fields intoEvidenceSnapshotand preserves nestedscore_inputsandkyc_resultpayloads. - Assert that
FeaturesResource.computereturnsjob_id,status,consent_id, andestimated_completion_ms. - Assert that
StatusResource.gethandlescompleted_atanderroras optional fields. - Verify webhook signatures against raw bytes and raw strings, including the
sha256=prefix. - Keep
mypystrictness andruffformatting aligned with the package configuration.
Key Classes Reference
| Class | Responsibility |
|---|---|
Consent (types.py) |
Consent record returned by create, get, and revoke |
Connection (types.py) |
Provider connection embedded in a consent |
KycCheckDetail (types.py) |
Single KYC or AML check result |
KycResult (types.py) |
Compliance result attached to a consent |
ComputeFeaturesResponse (types.py) |
Async feature job metadata |
JobStatusResponse (types.py) |
Async job polling result |
Score (types.py) |
Computed score, explanation, and evidence reference |
EvidenceSnapshot (types.py) |
Immutable audit snapshot |
TransactionListResponse (types.py) |
Paginated transaction collection |
WebhookEvent (types.py) |
Parsed webhook payload |
LitaError (errors.py) |
Base API exception |
LitaAuthError (errors.py) |
Auth failure exception |
LitaNotFoundError (errors.py) |
Missing resource exception |
LitaRateLimitError (errors.py) |
Rate limit exception with retry guidance |
LitaWebhookSignatureError (errors.py) |
Webhook signature verification failure |
ConsentsResource (resources/consents.py) |
Consent, score, transactions, and KYC operations |
EvidenceResource (resources/evidence.py) |
Evidence snapshot retrieval |
FeaturesResource (resources/features.py) |
Async feature computation |
StatusResource (resources/status.py) |
Async job polling |
construct_event (webhooks.py) |
Webhook signature verification and parsing |