Webhooks - Nordiska Embedded

Webhooks provide real-time notifications about changes in the card onboarding process. Your system will receive HTTP POST requests whenever significant events occur during the credit card application lifecycle.

How Webhooks Work

We guarantee delivery and ordered processing:

Event Generation: Onboarding events are generated when status changes occur
Conditional Enqueueing: Events are only enqueued if webhook delivery is configured for the tenant
Sequential Processing: Events are processed in order per onboarding ID using sequence numbers
Reliable Delivery: Failed deliveries are retried with exponential backoff

Configuration

Webhook endpoints must be configured by your integration contact person before going live. Configuration includes the webhook URL, signing secret, and optional authentication header.

Requirements

Your webhook endpoint must:

Accept HTTP POST requests with JSON payloads
Respond with HTTP 2XX status for successful processing
Process requests within 30 seconds (configurable)
Be accessible over HTTPS

Optional:

Verify webhook signatures for security

Webhook Configuration

Webhooks are configured per tenant in the system with:

Webhook URL: Your endpoint to receive notifications
Signing Secret: Used for HMAC signature verification
Authentication Header: Optional bearer token or API key

Retry Policy

The service implements a robust retry mechanism with exponential backoff:

Maximum Retries: 10 attempts (configurable)
Initial Delay: 100ms
Backoff Strategy: Exponential with jitter

After all retries are exhausted, the webhook event is marked as permanently failed.

Webhook Events

The system sends webhooks for these onboarding lifecycle events:

SIGNING_SESSION_CREATED

Triggered when a credit card application is approved and ready for document signing.

{
  "eventType": "SIGNING_SESSION_CREATED",
  "onboardingId": "7a0d9433-4f64-4f93-919c-5ab7d81eea55",
  "signingUrl": "https://sign.dev.nordiska.com/?sessionId=1fa6ef79-16e7-4665-ae78-c885e65e372b"
}

Required Actions:

Redirect customer to complete document signing

SIGNING_SESSION_COMPLETED

Triggered when a customer successfully completes document signing.

{
  "eventType": "SIGNING_SESSION_COMPLETED",
  "onboardingId": "7a0d9433-4f64-4f93-919c-5ab7d81eea55"
}

Required Actions:

Initiate card creation process

ONBOARDING_COMPLETED

Triggered when the entire onboarding process finishes successfully.

{
  "eventType": "ONBOARDING_COMPLETED",
  "onboardingId": "7a0d9433-4f64-4f93-919c-5ab7d81eea55",
  "engagementId": "8b9fd836-9d01-4c91-b0e0-17dfc26944e9"
}

Required Actions:

Store engagement ID for future reference

ONBOARDING_REJECTED

Triggered when a credit card application is declined during assessment.

{
  "eventType": "ONBOARDING_REJECTED",
  "onboardingId": "7a0d9433-4f64-4f93-919c-5ab7d81eea55",
  "rejectReason": "CREDIT_SCORING_DENIAL"
}

Rejection Reasons:

Reason	Description	Customer Action
`KYC_DENIAL`	Failed identity verification or sanctions screening	Contact support, provide additional documentation
`KYB_DENIAL`	Failed business verification	Contact support for business verification issues
`CREDIT_SCORING_DENIAL`	Insufficient creditworthiness based on bureau data	Can reapply after 3 months
`UNAUTHORIZED_SIGNATORY`	Individual not authorized to sign for business	Provide proof of signatory authorization
`INVALID_DOCUMENTS`	Submitted documents invalid or insufficient	Re-upload valid documents

ONBOARDING_FAILED

Triggered when a technical error occurs during the onboarding process.

{
  "eventType": "ONBOARDING_FAILED",
  "onboardingId": "7a0d9433-4f64-4f93-919c-5ab7d81eea55",
  "failureCode": "ADDRESS_MISMATCH"
}

Failure Codes:

Code	Description	Resolution
`INTERNAL_ERROR`	System error requiring investigation	Contact support, retry after resolution
`ADDRESS_MISMATCH`	Address doesn’t match official records	Update application with correct address
`NAME_MISMATCH`	Name doesn’t match official records	Verify spelling, provide correct legal name
`ID_VERIFICATION_FAILED`	Identity verification failed	Provide additional documentation
`TIMEOUT`	Process timeout occurred	Retry application

Webhook Security

All webhooks include security headers to verify authenticity and prevent replay attacks.

Headers

X-Card-Onboarding-Signature: a1b2c3d4e5f6...
X-Card-Onboarding-Timestamp: 2024-01-15T10:35:00Z
Authorization: Bearer your-auth-token
Content-Type: application/json

Signature Verification

The service generates HMAC-SHA256 signatures using the format timestamp:payload:

Event Ordering and Idempotency

Sequential Processing

The service guarantees that webhook events are delivered in the correct order per onboarding ID using:

Sequence Numbers: Each event gets an incrementing sequence number
Ordered Delivery: Events are processed in sequence number order
Blocking: If an earlier event fails, later events are blocked until retry succeeds

Need help with webhook implementation? Contact your integration specialist for technical support and configuration assistance.

​How Webhooks Work

​Configuration

​Requirements

​Webhook Configuration

​Retry Policy

​Webhook Events

​SIGNING_SESSION_CREATED

​SIGNING_SESSION_COMPLETED

​ONBOARDING_COMPLETED

​ONBOARDING_REJECTED

​ONBOARDING_FAILED

​Webhook Security

​Headers

​Signature Verification

​Event Ordering and Idempotency

​Sequential Processing

How Webhooks Work

Configuration

Requirements

Webhook Configuration

Retry Policy

Webhook Events

SIGNING_SESSION_CREATED

SIGNING_SESSION_COMPLETED

ONBOARDING_COMPLETED

ONBOARDING_REJECTED

ONBOARDING_FAILED

Webhook Security

Headers

Signature Verification

Event Ordering and Idempotency

Sequential Processing