---
title: "Notifications"
description: "Configure webhook notifications for credential issuance events."
stack: "Community Stack (open source) — version 0.21.0"
stack_version: "0.21.0"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/issuer2/notifications
generated: 2026-07-20
---
# 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

```json
{
  "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

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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).

```json
{
  "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:

```hocon
# 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:

```bash
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`

```javascript
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.

**Note:**

On connection, the SSE endpoint first sends an empty `data: {}` message as an initial handshake, before any session events. Guard against it in your handler (e.g. check `data.event` before acting), as shown in the example above where the `data.event === 'issuance_status'` check safely ignores it.

| 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

- [Issuer Profiles Configuration](https://docs.walt.id/community-stack/issuer2/configurations/config-files/issuer-profiles.md) – Add notifications to your profiles