#Notifications

The Issuer2 API supports webhook-based notifications for real-time updates on credential issuance events. Configure notifications at the profile level or override them per offer.

#Overview

Notifications allow your backend systems to receive real-time updates when:

A credential offer is resolved by a wallet
An access token is requested
A credential is issued
The issuance session status changes

This enables you to:

Track issuance progress
Update your database when credentials are claimed
Trigger downstream workflows
Audit credential issuance

#Configuration

Notifications are configured in the notifications object of a credential profile or as a runtime override when creating an offer.

#Basic Configuration

{
  "notifications": {
    "webhook": {
      "url": "https://your-server.com/webhook/issuance"
    }
  }
}

#Configuration Properties

Property	Type	Required	Description
`webhook.url`	String	Yes	The URL to receive webhook notifications

#Webhook Events

Your webhook endpoint will receive POST requests with JSON payloads for the following events:

#Event Structure

{
  "target": "session-id-123",
  "event": "event_type",
  "session": { ... }
}

Field	Description
`target`	The session/offer ID
`event`	The event type
`session`	Full session data as a JSON object

#Event Types

#`resolved_credential_offer`

Triggered when a wallet resolves the credential offer.

{
  "target": "session-id-123",
  "event": "resolved_credential_offer",
  "session": {
    "sessionId": "session-id-123",
    "credentialConfigurationId": "UniversityDegree_jwt_vc_json",
    "credentialOffer": {
      "credential_issuer": "http://localhost:7002",
      "credential_configuration_ids": ["UniversityDegree_jwt_vc_json"],
      "grants": { ... }
    }
  }
}

#`requested_token`

Triggered when a wallet requests an access token.

{
  "target": "session-id-123",
  "event": "requested_token",
  "session": {
    "sessionId": "session-id-123",
    "credentialConfigurationId": "UniversityDegree_jwt_vc_json"
  }
}

#`sdjwt_issue`

Triggered when an SD-JWT VC credential is issued.

{
  "target": "session-id-123",
  "event": "sdjwt_issue",
  "session": {
    "sessionId": "session-id-123",
    "credentialConfigurationId": "identity_credential_dc+sd-jwt"
  }
}

#`jwt_issue`

Triggered when a W3C JWT credential is issued.

{
  "target": "session-id-123",
  "event": "jwt_issue",
  "session": {
    "sessionId": "session-id-123",
    "credentialConfigurationId": "UniversityDegree_jwt_vc_json"
  }
}

#`generated_mdoc`

Triggered when an mDoc credential is generated.

{
  "target": "session-id-123",
  "event": "generated_mdoc",
  "session": {
    "sessionId": "session-id-123",
    "credentialConfigurationId": "org.iso.18013.5.1.mDL"
  }
}

#`issuance_status`

Triggered when the issuance session status changes (e.g., when issuance completes).

{
  "target": "session-id-123",
  "event": "issuance_status",
  "session": {
    "sessionId": "session-id-123",
    "credentialConfigurationId": "UniversityDegree_jwt_vc_json",
    "status": "SUCCESSFUL",
    "isClosed": true
  }
}

#Profile-Level Notifications

Configure notifications in your credential profile configuration file:

# issuer2-profiles.conf

profiles = {
  "notified-credential" = {
    name = "Notified Credential"
    credentialConfigurationId = "identity_credential_dc+sd-jwt"
    issuerKey = { ... }
    credentialData = { ... }
    notifications = {
      webhook = {
        url = "https://your-server.com/webhook/issuance"
      }
    }
  }
}

#Per-Offer Notifications

Override profile notifications for a specific offer using runtime overrides:

curl -X POST 'http://localhost:7002/issuer2/credential-offers' \
  -H 'Content-Type: application/json' \
  -d '{
    "profileId": "university-degree",
    "authMethod": "PRE_AUTHORIZED",
    "runtimeOverrides": {
      "notifications": {
        "webhook": {
          "url": "https://different-server.com/webhook/special-offer"
        }
      }
    }
  }'

#Alternative: Server-Sent Events (SSE)

For real-time monitoring in browser-based applications, the Issuer2 API also provides a Server-Sent Events (SSE) endpoint. This allows you to subscribe to session events directly from a browser without setting up a webhook server.

Endpoint: GET /issuer2/sessions/{sessionId}/events

const sessionId = 'abc123-def456-ghi789';
const eventSource = new EventSource(
  `http://localhost:7002/issuer2/sessions/${sessionId}/events`
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Session event:', data.event);
  
  if (data.event === 'issuance_status' && data.session.status === 'SUCCESSFUL') {
    console.log('Credential issued successfully!');
    eventSource.close();
  }
};

The SSE stream emits the same event types and payload structure as webhooks.

Feature	Webhooks	SSE
Best for	Server-to-server	Browser/client apps
Connection	Push to your server	Client pulls from issuer
Reliability	More reliable	May disconnect
Setup	Requires public endpoint	No server needed

#Next Steps

Credential Profiles – Add notifications to your profiles

Last updated on June 15, 2026

Data Functions Full API Reference