Notification Endpoint

EUDIPLO supports the OID4VCI Notification Endpoint, allowing wallets to notify the issuer when credential processing events occur (acceptance, deletion, failure).

:::note Implementation Status This page documents the notification endpoint as implemented. Some behaviors may be subject to change based on spec evolution and wallet compatibility testing. :::

Overview

The notification endpoint provides a way for wallets to send event notifications back to the issuer after receiving credentials. This enables issuers to:

• Track credential lifecycle events (accepted, deleted, failed)
• Audit wallet interactions
• Implement business logic based on wallet actions

Endpoint

POST /{tenant}/notification

The endpoint is publicly accessible (no authentication required from the wallet).

Request Format

Wallets send a POST request with a JSON body containing the notification:

{
    "notification_id": "550e8400-e29b-41d4-a716-446655440000",
    "event": "credential_accepted",
    "event_description": "User accepted the credential",
    "credential_id": "abc123"
}

Request Fields

Field	Type	Required	Description
notification_id	string	No	Unique identifier for this notification (wallet-generated UUID)
event	string	Yes	Event type (see below)
event_description	string	No	Human-readable description of the event
credential_id	string	No	ID of the credential this notification relates to

Event Types

The OID4VCI spec defines three standard event types:

Event	Description
credential_accepted	Wallet successfully processed and stored the credential
credential_deleted	User deleted the credential from the wallet
credential_failure	Wallet failed to process the credential

Response

The endpoint returns:

• 204 No Content on success
• 400 Bad Request if the notification payload is invalid

Webhook Integration

When a wallet sends a notification, EUDIPLO can forward it to a configured webhook endpoint.

Configuring Webhooks

Webhook endpoints can be configured at two levels:

1. Credential Configuration Level: Set webhookEndpointId in the Credential Configuration to apply to all offers of that type.

2. Offer Level: Set webhookEndpointId when creating the offer to override the credential configuration setting for that specific offer.

Example (credential configuration):

{
    "id": "employee-badge",
    "webhookEndpointId": "notification-webhook"
}

Example (offer override):

{
    "response_type": "uri",
    "flow": "pre_authorized_code",
    "credentialConfigurationIds": ["employee-badge"],
    "webhookEndpointId": "staging-notification-webhook"
}

Webhook Payload

When forwarding the notification, EUDIPLO sends a POST request to the configured webhook URL with:

{
    "session": "a6318799-dff4-4b60-9d1d-58703611bd23",
    "credential_configuration_id": "employee-badge",
    "notification": {
        "notification_id": "550e8400-e29b-41d4-a716-446655440000",
        "event": "credential_accepted",
        "event_description": "User accepted the credential",
        "credential_id": "abc123"
    }
}

Field	Type	Description
session	string	The issuance session ID
credential_configuration_id	string	The credential configuration ID
notification	object	The original notification from the wallet

Use Cases

Audit Trail

Log wallet acceptance events for compliance or analytics:

// Webhook handler
app.post('/webhooks/notification', (req, res) => {
    const { session, notification } = req.body;
    
    if (notification.event === 'credential_accepted') {
        auditLog.record({
            session,
            event: 'credential_accepted',
            timestamp: new Date()
        });
    }
    
    res.sendStatus(200);
});

User Onboarding

Complete a multi-step onboarding flow when the user accepts the credential:

if (notification.event === 'credential_accepted') {
    await completeOnboarding(session);
    await sendWelcomeEmail(session);
}

Credential Lifecycle

Track credential deletion for reissuance workflows:

if (notification.event === 'credential_deleted') {
    await markCredentialAsDeleted(notification.credential_id);
    await offerReissuance(session);
}

Best Practices

1. Create Webhook Endpoints First: Before referencing a webhook in a credential configuration or offer, create the webhook endpoint resource via the API.

2. Validate Webhook Signatures: EUDIPLO signs webhook requests. Validate the signature to ensure the request came from your EUDIPLO instance.

3. Handle Retries: Webhooks may be retried on failure. Implement idempotency using notification_id to avoid duplicate processing.

4. Log Failures: If your webhook endpoint is unavailable, EUDIPLO logs the failure. Monitor webhook delivery success rates.

5. Use Offer-Level Overrides for Testing: Test with different webhook endpoints during development by overriding at offer creation time.

Related Documentation

• Credential Configuration — Configuring credential-level webhooks
• Credential Offers — Configuring offer-level webhooks
• Architecture: Webhooks — Webhook integration patterns
• API Reference — Webhook Endpoint management API