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"
}
- 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"
}
- 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"
}
- 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"
}
| 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"
}
| 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.
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. 
