How to query events

In this guide we will learn how to retrieve a specific set of events (e.g. VerificationEvent, IssuanceEvent) in a specific scope of the enterprise stack (e.g. in an organization or tenant). Events are enabled by default, meaning as soon as you start the Enterprise Stack events start to be recorded and stored in the connected Enterprise Stack database. At the moment, we support the events shown below.

Supported Events

  • IssuanceEvent: This event tracks the status of credential offers that are initiated through the credentials/issue endpoint of the issuer service.
  • VerificationEvent: This event tracks the status of credential requests that are initiated via the credentials/verify endpoint of the verifier service.

Query events without filters

To retrieve a set of events, we can use the /events/query endpoint along with an optional filter in our request. In this example, we will not apply any filter; instead, we will send an empty {} in the body of the request. As a result, this will return all events that occurred within the organization specified in the query parameter.

We can only request events from one specific organization at a time. It is not possible to request events from two different organizations simultaneously.


CURL

Endpoint: /v1/events/query | API Reference

Ensure the organization is set to one your user has read access on when filtering for events.

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/events/query?organization={orgID}' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{}'

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.

Body

{}

Response

  • 200 - Events retrieved successfully.

Example Response

[
  {
    "type": "id.walt.commons.events.IssuanceEvent",
    "eventType": "IssuanceEvent",
    "_id": "2a7b554a-37c7-4ae6-809f-2559bfa47913",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.issuer2",
    "timestamp": 1741192586004,
    "action": {
      "type": "init_session"
    },
    "status": {
      "type": "Open"
    },
    "callId": "436a8a95-3290-4b65-94b9-a0970012d91c",
    "error": null,
    "sessionId": "fb517c9d-5178-48a9-8d39-9fd89d857d53",
    "credentialConfigurationId": "identity_credential_vc+sd-jwt",
    "format": "vc+sd-jwt"
  },
  {
    "type": "id.walt.commons.events.IssuanceEvent",
    "eventType": "IssuanceEvent",
    "_id": "a8d78606-b297-484d-af2f-48a56b0b4732",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.issuer2",
    "timestamp": 1741192721792,
    "action": {
      "type": "process_request"
    },
    "status": {
      "type": "Success"
    },
    "callId": "af341708-5722-4e04-b3c2-6b99008c7316",
    "error": null,
    "sessionId": "fb517c9d-5178-48a9-8d39-9fd89d857d53",
    "credentialConfigurationId": "identity_credential_vc+sd-jwt",
    "format": "vc+sd-jwt",
    "proofType": "jwt",
    "holderId": "hHAsP0_f0yRK3tKfH854d-ZG7GlApwYNpH1JFaStPuc"
  },
  {
    "type": "id.walt.commons.events.VerificationEvent",
    "eventType": "VerificationEvent",
    "_id": "e7a33f7b-024c-4ff7-980b-d47f7ed825e7",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.verifier1",
    "timestamp": 1741252466353,
    "action": {
      "type": "init_session"
    },
    "status": {
      "type": "Open"
    },
    "callId": "9c2f6b21-8d99-4a41-8950-66f5aa4485d2",
    "error": null,
    "sessionId": "bec96d15-6fe9-4553-a873-82b2ef270b15",
    "format": "vc+sd-jwt",
    "signatureAlgorithm": "",
    "credentialType": "identity_credential"
  },
  {
    "type": "id.walt.commons.events.VerificationEvent",
    "eventType": "VerificationEvent",
    "_id": "735c7ae3-8e2b-4a5c-a257-95eec651d133",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.verifier1",
    "timestamp": 1741252709251,
    "action": {
      "type": "process_request"
    },
    "status": {
      "type": "Failure"
    },
    "callId": "c6a15ee3-b5b9-4294-a942-049b68bda0d8",
    "error": null,
    "sessionId": "bec96d15-6fe9-4553-a873-82b2ef270b15",
    "format": "vc+sd-jwt",
    "signatureAlgorithm": "",
    "credentialType": "identity_credential",
    "holderId": "DbEu8NYzFYZ8WSMapj1Y5JJCRXWdjF1r8I_UyFrBe-Q"
  }
]

The response we received includes two distinct events: the IssuanceEvent and the VerificationEvent. Each of these events appears twice as they move through different stages. Initially, the status property is set to Open, and it changes to either Success or Failure as the events progress.

To learn more about each event's data structure in detail, pleas go here.

Query events with filter

To retrieve a set of events, we can use the /events/query endpoint along with an optional filter in our request. In this example, we will use a filter to only see events that are coming from a specific issuer service.

We can only request events from one specific organization at a time. It is not possible to request events from two different organizations simultaneously.


CURL

Endpoint: /v1/events/query | API Reference

Ensure the organization is set to one your user has read access on when filtering for events.

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/events/query?organization={orgID}' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "target": [
    "waltid.mycustomer.issuer2"
  ]
}'

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.

Body

{
  "target": [
    "waltid.mycustomer.issuer2"
  ]
}

Here we specify that we only want to receive events that happened in a specific target. Learn more about how to craft your filter here

Response

  • 200 - Events retrieved successfully.

Example Response

[
  {
    "type": "id.walt.commons.events.IssuanceEvent",
    "eventType": "IssuanceEvent",
    "_id": "2a7b554a-37c7-4ae6-809f-2559bfa47913",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.issuer2",
    "timestamp": 1741192586004,
    "action": {
      "type": "init_session"
    },
    "status": {
      "type": "Open"
    },
    "callId": "436a8a95-3290-4b65-94b9-a0970012d91c",
    "error": null,
    "sessionId": "fb517c9d-5178-48a9-8d39-9fd89d857d53",
    "credentialConfigurationId": "identity_credential_vc+sd-jwt",
    "format": "vc+sd-jwt"
  },
  {
    "type": "id.walt.commons.events.IssuanceEvent",
    "eventType": "IssuanceEvent",
    "_id": "a8d78606-b297-484d-af2f-48a56b0b4732",
    "originator": null,
    "organization": "waltid",
    "target": "waltid.mycustomer.issuer2",
    "timestamp": 1741192721792,
    "action": {
      "type": "process_request"
    },
    "status": {
      "type": "Success"
    },
    "callId": "af341708-5722-4e04-b3c2-6b99008c7316",
    "error": null,
    "sessionId": "fb517c9d-5178-48a9-8d39-9fd89d857d53",
    "credentialConfigurationId": "identity_credential_vc+sd-jwt",
    "format": "vc+sd-jwt",
    "proofType": "jwt",
    "holderId": "hHAsP0_f0yRK3tKfH854d-ZG7GlApwYNpH1JFaStPuc"
  }
]

Crafting the Filter

When making requests to the events/query endpoint, you can include a filter object {} within the request body. This filter allows you to specify criteria for selecting the events you are interested in.

Filter Structure

The filter comprises general filters applicable to all event types and specific filters tailored for certain event types. Each filter consists of a key (representing the field to be filtered) and an array of one or more values to match against.

General Filters

  • eventType: Specifies the type of event. Possible values are VerificationEvent or IssuanceEvent.
  • status: Indicates the status of the event. Possible values are Open, Success, or Failure.
  • action: Describes the action taken. Possible values are init_session or process_request.
  • fromTimestamp: A Unix timestamp in milliseconds marking the start of the time range, e.g., 1741192586004.
  • toTimestamp: A Unix timestamp in milliseconds marking the end of the time range, e.g., 1741192586004.
  • callId: A UUID representing the call, e.g., "436a8a95-3290-4b65-94b9-a0970012d91c".
  • target: The service or tenant where the event was triggered, e.g., waltid.tenant1 or waltid.tenant1.issuer1.

Event-Specific Filters

For specific event types, you need to include additional filters within a nested object. This nested object should be named according to the event type: issuanceEventFilter for Issuance Events and verificationEventFilter for Verification Events.

Issuance Event Filters

These filters should be included in an object called issuanceEventFilter:

  • credentialConfigurationId: The ID of the credential configuration being issued, e.g., identity_credential_vc+sd-jwt.
  • format: The format of the credential being issued, e.g., jwt_vc_json or vc+sd-jwt.
  • sessionId: The OID4VC session ID.

Verification Event Filters

These filters should be included in an object called verificationEventFilter:

  • format: The format of the credential being requested, e.g., jwt_vc_json or vc+sd-jwt.
  • sessionId: The OID4VP session ID.
  • signatureAlgorithm: The signature algorithm used.
  • credentialType: The type of credential requested, e.g., identity_credential.
  • holderId: The ID of the holder, e.g., DbEu8NYzFYZ8WSMapj1Y5JJCRXWdjF1r8I_UyFrBe.

Example Queries

Verification Event Filter Example:

{
  // GENERAL EVENT FILTERS
  "eventType": [
    "VerificationEvent"
  ],
  "status": [
    "Open",
    "Success",
    "Failure"
  ],
  "action": [
    "init_session",
    "process_request"
  ],
  // EVENT SPECIFIC FILTERS
  "verificationEventFilter": {
    "format": [
      "vc+sd-jwt",
      "jwt_vc_json"
    ]
  }
}

Issuance Event Filter Example:

{
  // GENERAL EVENT FILTERS
  "eventType": [
    "IssuanceEvent"
  ],
  "status": [
    "Open",
    "Success",
    "Failure"
  ],
  "action": [
    "init_session",
    "process_request"
  ],
  // EVENT SPECIFIC FILTERS
  "issuanceEventFilter": {
    "format": [
      "vc+sd-jwt",
      "jwt_vc_json"
    ]
  }
}
OverviewHow to retrieve Metrics