> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nordiska.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Complete guide to webhook implementation for card onboarding events

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:

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

## Configuration

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

### 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.

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

**Required Actions**:

1. Redirect customer to complete document signing

### SIGNING\_SESSION\_COMPLETED

Triggered when a customer successfully completes document signing.

```json theme={null}
{
  "eventType": "SIGNING_SESSION_COMPLETED",
  "onboardingId": "7a0d9433-4f64-4f93-919c-5ab7d81eea55"
}
```

**Required Actions**:

1. Initiate card creation process

### ONBOARDING\_COMPLETED

Triggered when the entire onboarding process finishes successfully.

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

**Required Actions**:

1. Store engagement ID for future reference

### ONBOARDING\_REJECTED

Triggered when a credit card application is declined during assessment.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

```http theme={null}
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.