Webhook Events
Organisation Wallet Suite by iGrant.io provides webhooks to notify your application about important events in credential issuance (OpenID4VCI), verification (OpenID4VP) and your organisation's holder wallet. This page lists all available event types and what they mean, and explains how to read the event body, verify the signature, and handle retries and duplicates.
Webhook Management
Before receiving webhook events, you need to configure your webhook endpoints. The following APIs are available for managing webhooks:
| API | Description | Documentation |
|---|---|---|
| Create Webhook | Create a webhook endpoint and subscribe to event types | Create Webhook |
| Read Webhook | Get the details of a webhook | Read Webhook |
| Update Webhook | Replace the configuration of a webhook | Update Webhook |
| Delete Webhook | Remove a webhook endpoint | Delete Webhook |
| List Webhooks | Get all the webhooks, with the status of the last delivery of each webhook | List Webhooks |
| Ping Webhook | Check that the payload URL responds | Ping Webhook |
| Read webhook event types | Get the event types that a webhook of your organisation can subscribe to | Read webhook event types |
| List webhook content types | Get the payload content types (only application/json) | List webhook content types |
| List webhook deliveries | Get the deliveries of a webhook, with the status of each delivery | List webhook deliveries |
| Read webhook delivery | Get one delivery of a webhook | Read webhook delivery |
To subscribe to the events of the organisation wallet (the ows.* types), add them to subscribedEvents.digitalWalletWebhook of the webhook.
The event type list (GET /v4/config/platform/webhooks/event-types) returns the event types that a webhook of your organisation can subscribe to, sorted by type, each with a description, the version of its body and its product feature:
{
"eventTypes": [
{
"type": "ows.issuer.issuance_history.credential_issued",
"description": "The issuer signed and returned the first credential of the issuance history, with all its batch copies.",
"schemaVersion": 1,
"feature": "issuerVerifier"
}
]
}
The content type list (GET /v4/config/platform/webhooks/payload/content-types) returns {"contentTypes": ["application/json"]}, as every event is posted as a JSON body.
Event types and features
The event types follow the features of your organisation. Each event type has one product feature:
| Event types | Feature |
|---|---|
ows.issuer.*, ows.verifier.* | issuerVerifier (Issuer & Verifier) |
ows.holder.* | walletUnit (Wallet Unit) |
consent.*, data.* | consentManagement (Consent Management) |
datamarketplace.* | dataDisclosureAgreements (Data Marketplace) |
- The event type list has only the types of the features that are on for your organisation (Read organisation features). A feature is on when the platform admin turned it on and the installation has the services that it needs. A sandbox organisation has the features of its main organisation.
- A create or update request with a new event type of a feature that is off gets
403witherrorKeyfeature_disabled. A new event type of a service that the installation does not have gets400witherrorKeyservice_not_installed. An event type that the webhook already has stays. - Your organisation gets no events of a feature that is off, also when a webhook subscribes to its types. When the feature is on again, the webhook gets the new events.
Issuer Events
Issuer events notify you about each step of an issuance history. An issuance history is the record of one credential configuration offered to one wallet (or of an issuance that a wallet started), together with the credentials that the issuer signed for it. When you issue a credential definition with N credential configurations, a single credential offer creates N issuance histories, so you receive N created events that share the same data.issuanceHistory.offerId. After each step, the issuance history has the status of the same name as the event, with one exception: the created event sets the status offer_sent. This also applies to an issuance that a wallet started, even though no offer was sent.
| Event type | Meaning |
|---|---|
ows.issuer.issuance_history.created | A new issuance history has started: an issue call created a credential offer (one issuance history for each credential configuration of the definition), a wallet started the issuance, or a wallet reused an offer. The status of the issuance history is offer_sent. |
ows.issuer.issuance_history.offer_retrieved | The wallet fetched the credential offer for the first time. |
ows.issuer.issuance_history.token_issued | The token endpoint issued an access token for the issuance history, in exchange for a pre-authorised code, an authorisation code or a refresh token. data.grant tells you which. |
ows.issuer.issuance_history.claims_supplied | You provided the claims of a deferred issuance history. |
ows.issuer.issuance_history.credential_deferred | The wallet requested the credential before the claims of the deferred issuance history were available. The wallet receives a transaction ID and tries again later. |
ows.issuer.issuance_history.credential_issued | The issuer signed and returned the first credential of the issuance history, including all its batch copies. |
ows.issuer.issuance_history.credential_reissued | The issuer signed and returned a new version of the credential of the issuance history. |
ows.issuer.issuance_history.credential_accepted | The wallet told the issuer that it accepted the credential. |
ows.issuer.issuance_history.credential_deleted | The wallet told the issuer that the holder deleted the credential. When the credential configuration has revocation.revokeWhenHolderDeletes: true, the issuer also revokes the credential in this step: data.revoked is then true, and no separate revoked event is sent. |
ows.issuer.issuance_history.credential_failed | The wallet told the issuer that it could not store or use the credential. |
ows.issuer.issuance_history.denied | The issuer rejected the issuance, for example because the wallet attestation or the proof of possession was not valid. data.reason contains the error. |
ows.issuer.issuance_history.revoked | The issuer revoked the issued credentials of the issuance history, through the API, because the organisation was deactivated, or by an issuer rule. A revocation is final. |
ows.issuer.issuance_history.expired | The current grant of an issuance history in progress expired before a credential was issued. When a token request names only some of the configurations of an offer, the other issuance histories of the offer expire immediately, because the pre-authorised code can be used only once. |
ows.issuer.issuance_history.deleted | You deleted the issuance history. The other issuance histories of the same offer are not affected. |
Changes to credential definitions and to the issuer configuration do not send events, as you make them yourself.
Verifier Events
Verifier events notify you about each step of a verification, that is, the verifier's presentation request and the wallet's response to it.
| Event type | Meaning |
|---|---|
ows.verifier.verification.created | A new verification has started: the verifier created a presentation request. |
ows.verifier.verification.request_retrieved | The wallet fetched the presentation request for the first time. |
ows.verifier.verification.presentation_received | The wallet sent a presentation and the verifier checked it. data.verification.isVerified holds the result. |
ows.verifier.verification.declined | The wallet responded to the presentation request with an error, for example because the holder declined. There is no presentation, and data.reason contains the wallet's error. |
ows.verifier.verification.revalidated | You revalidated the received presentation. data.verification.isVerified holds the result. |
ows.verifier.verification.deleted | You deleted the verification. |
Changes to presentation definitions and to the verifier configuration do not send events. The expiry of a presentation request is not a step, so it has no event either.
Holder Events
Holder events notify you about events in your organisation's wallet when it receives credentials and responds to presentation requests.
| Event type | Meaning |
|---|---|
ows.holder.credential.created | The holder wallet accepted a credential offer, but the credential has not arrived yet. The wallet is waiting for a transaction code, an authorisation code or a deferred credential. |
ows.holder.credential.received | The holder wallet received the credential from its issuer. |
ows.holder.credential.reissued | The holder wallet received a new version of the credential from its issuer. |
ows.holder.credential.accepted | You accepted the held credential. |
ows.holder.credential.revoked | A status check found that the issuer revoked the held credential. |
ows.holder.credential.suspended | A status check found that the issuer suspended the held credential. |
ows.holder.credential.reactivated | A status check found that the issuer made a revoked or suspended held credential valid again. |
ows.holder.credential.deleted | You deleted the held credential. |
ows.holder.presentation.request_received | The holder wallet received a presentation request. |
ows.holder.presentation.sent | The holder wallet sent the presentation to the verifier. |
ows.holder.presentation.deleted | You deleted the presentation. |
Changes to the holder configuration do not send events.
Event Body
The request body is the event itself. It is the same for every webhook and every delivery attempt, so the event ID stays the same; the values that change with each delivery are in the headers.
| Field | Type | Description |
|---|---|---|
id | string | The event ID, a lower-case UUID. Use it to detect duplicates. |
type | string | The event type, for example ows.issuer.issuance_history.credential_issued. |
schemaVersion | integer | The version of the body of the event type, currently 1. Adding or removing a member, or adding a new value to a type, creates a new version. |
occurredAt | string | The time of the step, in RFC 3339 format in UTC (for example 2026-11-05T08:00:00Z). |
organisationId | string | The ID of your organisation. For an event of a sandbox organisation, this is the ID of the main organisation. |
sandboxOrganisationId | string or null | The ID of the sandbox organisation, or null for the main organisation. Always present. |
subject | object | The resource that the event is about: type (issuance_history, verification, credential or presentation), id (for an issuance history, the credential exchange ID), and sequence, the sequence number of the event for this resource. |
data | object | A summary of the resource after the step, plus any data specific to the event type. |
All times are RFC 3339 strings in UTC. Enum values are in snake_case, while identifiers from the standards keep their original form (for example dc+sd-jwt and mso_mdoc). The body never contains tokens, claims, proofs, attestations, credential offer URIs, pre-authorised codes, transaction codes or presentation content, and it stays small (about 2 KB at most) however often a credential is re-issued. If you need more data, read the resource from the API using the ID in the event.
The data of the issuer events
Every issuer event has data.issuanceHistory, a summary of the issuance history. It has the same field names and values as the issuance history list of the API.
| Field | Type | Description |
|---|---|---|
credentialExchangeId | string | The credential exchange ID, which is the ID of the issuance history. |
credentialDefinitionId | string or null | The ID of the credential definition. |
credentialConfigurationId | string or null | The ID of the credential configuration. |
format | string or null | The credential format, for example dc+sd-jwt or mso_mdoc. |
mode | string | in_time or deferred. |
origin | string | How the issuance started: offer (an issue call created a credential offer), wallet_initiated (a wallet started the issuance) or offer_reuse (a wallet used an offer again). |
offerId | string or null | The ID of the credential offer. The issuance histories of one offer have the same offerId. |
status | string | offer_sent, offer_retrieved, token_issued, credential_deferred, claims_supplied, credential_issued, credential_accepted, credential_deleted, denied or expired. A revocation is not a status; it is recorded in revokedAt. |
revokedAt | string or null | The time of the revocation, or null when the issuer did not revoke the credentials. |
individualId | string or null | The ID of the individual. |
clientId | string or null | The client identifier of the wallet. |
reissueCount | integer | The number of times that the issuer re-issued the credential. |
createdAt | string | The time when the issuance history was created. |
updatedAt | string | The time of the last change of the issuance history. |
issuedAt | string or null | The time when the issuer issued the first credential. |
lastReissuedAt | string or null | The time of the last re-issuance, or null when the issuer did not re-issue the credential. |
Some issuer events have more members in data:
| Field | Events | Description |
|---|---|---|
credential | credential_issued, credential_reissued, credential_accepted, credential_deleted, credential_failed | The issued credential version of the step, without its token (see the next table). For credential_accepted, credential_deleted and credential_failed, which come from a wallet notification, it is null when the issuer cannot find the version that the wallet refers to. |
grant | token_issued | pre_authorised_code, authorisation_code or refresh_token. |
revoked | credential_deleted | true when the issuer revoked the credential in the same step. |
reason | denied, credential_failed, revoked | An object with code and description (see the reason table below). |
credentials | revoked | Up to 10 of the revoked credentials, newest first. Each item has id, version and copy (the index of the batch copy, 0 without a batch). |
credentialCount | revoked | The total number of credentials revoked in the step. To get all of them, use List issued credentials for the issuance history. |
The members of data.credential:
| Field | Type | Description |
|---|---|---|
id | string | The ID of the issued credential. |
version | integer | The version of the credential: 1 for the first credential, and one more for each re-issuance. |
copies | integer | The number of batch copies of this version (1 without a batch). |
issuedAt | string | The time when the issuer issued this version. |
validUntil | string or null | The end of the validity of this version, or null when it has no end. |
holderKeyChanged | boolean | true when the holder key of this version is not the key of the previous version. |
The values of data.reason:
| Event | code | description |
|---|---|---|
denied | The error ID, for example issuance.wallet_attestation_not_verified. | The description of the error. |
credential_failed | wallet.credential_failure | The text that the wallet sent, at most 500 characters. |
revoked | revocation_requested, for a revocation through the API. | The reason of the request, or an empty text. |
revoked | organisation_deactivated, when the organisation was deactivated. | An empty text. |
The data of the verifier events
Every verifier event has data.verification, a summary of the verification:
| Field | Type | Description |
|---|---|---|
id | string | The ID of the verification. |
presentationDefinitionId | string or null | The ID of the presentation definition. |
status | string | request_sent, request_received or presentation_acked. |
isVerified | boolean | true when the verifier verified the presentation. |
responseMode | string or null | The response mode of the presentation request, for example direct_post.jwt. |
credentialExchangeId | string or null | The credential exchange ID of the issuance history of a dynamic credential request. |
individualId | string or null | The ID of the individual. |
dataAgreementId | string or null | The ID of the data agreement. |
createdAt | string | The time when the verification was created. |
updatedAt | string | The time of the last change of the verification. |
The declined event also has data.reason:
| Field | Description |
|---|---|
code | wallet.<error> with the OAuth error code of the wallet, for example wallet.access_denied. When the error of the wallet is not an error code, code is wallet.error_response. |
description | The error description of the wallet, at most 500 characters. |
The data of the holder events
The ows.holder.credential.* events have data.credential, a summary of the held credential:
| Field | Type | Description |
|---|---|---|
id | string | The ID of the held credential. |
credentialFormat | string or null | The credential format, for example dc+sd-jwt. |
credentialConfigurationId | string or null | The ID of the credential configuration at the issuer. |
credentialIssuer | string or null | The identifier of the credential issuer. |
credentialStatus | string or null | credential_pending (the credential has not arrived yet), credential_acked (the holder wallet received the credential), credential_accepted (you accepted the credential) or credential_archived (a wallet unit attestation that a newer one replaced). |
revocationStatus | string or null | operational, revoked, suspended or null. |
isWalletUnitAttestation | boolean | true when the credential is a wallet unit attestation. |
batchId | string or null | The ID of the batch of the credential. |
refreshCount | integer | The number of times that the issuer re-issued the credential. |
createdAt | string | The time when the held credential was created. |
updatedAt | string | The time of the last change of the held credential. |
issuedAt | string or null | The time when the issuer issued the credential. |
lastRefreshedAt | string or null | The time of the last re-issuance. |
The ows.holder.presentation.* events have data.presentation, a summary of the presentation:
| Field | Type | Description |
|---|---|---|
id | string | The ID of the presentation. |
status | string | presentation_pending, presentation_acked, or request_refused for a request that the wallet rejected locally (OpenID4VP 1.0 section 5.9.2). A sent event never has request_refused. |
clientId | string or null | The client identifier of the verifier. |
clientMetadata | object | clientName: the name of the verifier, or null. |
createdAt | string | The time when the presentation was created. |
updatedAt | string | The time of the last change of the presentation. |
Every member of a summary is always present; a member without a value is null.
Issuer event example
POST /hooks/igrant HTTP/1.1
Content-Type: application/json
User-Agent: IGrant-Hookshot/1.0
X-IGrant-Event-Id: 0193f0b2-6c1e-7c4a-9a51-2f0d5e1b7a16
X-IGrant-Event-Type: ows.issuer.issuance_history.credential_issued
X-IGrant-Webhook-Id: 67f770936e45cf84e6880d25
X-IGrant-Delivery-Id: 67f770eec8426b0b55e30c2e
X-IGrant-Delivery-Attempt: 1
X-IGrant-Signature: t=1793865601,v1=5d41402abc4b2a76b9719d911017c592ae8f4e2c3b1d0a9f8e7d6c5b4a392817
{
"id": "0193f0b2-6c1e-7c4a-9a51-2f0d5e1b7a16",
"type": "ows.issuer.issuance_history.credential_issued",
"schemaVersion": 1,
"occurredAt": "2026-11-05T08:00:00Z",
"organisationId": "64ec561de2f6a8000142c671",
"sandboxOrganisationId": null,
"subject": {
"type": "issuance_history",
"id": "3e154218-6a1c-4b2f-9d0e-7c5a1f2b8d40",
"sequence": 4
},
"data": {
"issuanceHistory": {
"credentialExchangeId": "3e154218-6a1c-4b2f-9d0e-7c5a1f2b8d40",
"credentialDefinitionId": "a79fb535-2c4d-4e1f-8b6a-0d9c3e7f1a52",
"credentialConfigurationId": "urn:eudi:pid:1OuMMEeW6",
"format": "dc+sd-jwt",
"mode": "in_time",
"origin": "offer",
"offerId": "c0f5e2a1-9b3d-4c7e-8a6f-1d2b3c4e5f60",
"status": "credential_issued",
"revokedAt": null,
"individualId": "ind-1",
"clientId": "https://wallet.example",
"reissueCount": 0,
"createdAt": "2026-11-05T07:59:10Z",
"updatedAt": "2026-11-05T08:00:00Z",
"issuedAt": "2026-11-05T08:00:00Z",
"lastReissuedAt": null
},
"credential": {
"id": "5b7c9d1e-3f2a-4b6c-8d0e-1f2a3b4c5d6e",
"version": 1,
"copies": 1,
"issuedAt": "2026-11-05T08:00:00Z",
"validUntil": "2027-05-04T08:00:00Z",
"holderKeyChanged": false
}
}
}
The body is sent in compact form, without white space between tokens. The examples on this page are formatted for readability.
Verifier event example
{
"id": "0193f0b2-6c1e-7c4a-9a51-2f0d5e1b7b15",
"type": "ows.verifier.verification.presentation_received",
"schemaVersion": 1,
"occurredAt": "2026-11-05T08:00:40Z",
"organisationId": "64ec561de2f6a8000142c671",
"sandboxOrganisationId": null,
"subject": {
"type": "verification",
"id": "5b1e7c2a-3d4f-4a6b-8c9d-0e1f2a3b4c5d",
"sequence": 3
},
"data": {
"verification": {
"id": "5b1e7c2a-3d4f-4a6b-8c9d-0e1f2a3b4c5d",
"presentationDefinitionId": "9c2d4e6f-1a3b-4c5d-8e7f-0a1b2c3d4e5f",
"status": "presentation_acked",
"isVerified": true,
"responseMode": "direct_post.jwt",
"credentialExchangeId": null,
"individualId": "ind-1",
"dataAgreementId": null,
"createdAt": "2026-11-05T08:00:00Z",
"updatedAt": "2026-11-05T08:00:40Z"
}
}
}
Headers
| Header | Description |
|---|---|
Content-Type | application/json. |
X-IGrant-Event-Id | The event ID (id of the body). |
X-IGrant-Event-Type | The event type (type of the body). |
X-IGrant-Webhook-Id | The ID of the webhook. |
X-IGrant-Delivery-Id | The ID of the delivery of this event to this webhook. All attempts of a delivery share the same ID. |
X-IGrant-Delivery-Attempt | The attempt number, from 1 to 7. |
X-IGrant-Signature | t=<Unix seconds of the attempt>,v1=<hex>. Sent when the webhook has a secret key. |
Webhook Security
When the webhook has a secret key, each attempt includes an X-IGrant-Signature header that allows you to verify the authenticity of the event: t=<Unix seconds>,v1=<hex>. v1 is the HMAC-SHA256 of t + "." + body with the webhook's secret key, in lower-case hexadecimal, where body is the exact bytes of the request body. The JSON is not re-encoded after signing, so compute the HMAC over the bytes you received, before you parse them.
To verify a webhook signature:
- Extract
tandv1from the header. - Reject the request if
tis more than 5 minutes away from your clock. - Get the raw request body as bytes. Do not parse it and encode it again.
- Compute the HMAC-SHA256 of
t + "." + bodyusing your webhook's secret key, and encode it as lower-case hexadecimal. - Compare the result with
v1in constant time.
Example verification code in Go:
func verifyWebhookSignature(header string, secretKey string, body []byte, now time.Time) bool {
var t, v1 string
for _, part := range strings.Split(header, ",") {
key, value, _ := strings.Cut(part, "=")
switch key {
case "t":
t = value
case "v1":
v1 = value
}
}
seconds, err := strconv.ParseInt(t, 10, 64)
if err != nil || now.Sub(time.Unix(seconds, 0)).Abs() > 5*time.Minute {
return false
}
mac := hmac.New(sha256.New, []byte(secretKey))
mac.Write([]byte(t + "."))
mac.Write(body)
expected := hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(v1))
}
Example in Node.js (Express, with the raw body):
const crypto = require('crypto');
app.post('/hooks/igrant', express.raw({ type: 'application/json' }), (req, res) => {
const header = req.get('X-IGrant-Signature') || '';
const parts = Object.fromEntries(header.split(',').map((part) => part.split('=')));
const ageSeconds = Math.abs(Date.now() / 1000 - Number(parts.t));
const expected = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(`${parts.t}.`)
.update(req.body)
.digest('hex');
const valid =
ageSeconds <= 300 &&
typeof parts.v1 === 'string' &&
parts.v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body.toString('utf8'));
// Store event.id to remove duplicates, then process the event.
res.sendStatus(200);
});
Security Best Practices
- Always verify the webhook signature before processing the body.
- Reject a
tthat is more than 5 minutes away from your clock, to prevent replay attacks. - Keep your webhook secret key secure and never share it.
- Use HTTPS endpoints for webhook delivery.
- Respond quickly with a
2xxstatus code, and process the event after you have responded.
Delivery
- Success: only a
2xxresponse within 10 seconds counts as a success. Redirects are not followed, and a3xx,4xxor5xxresponse, a timeout or a transport error counts as a failure. - Retries: after a failed attempt, the delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours, so there are 7 attempts in total. Each attempt has the same body and event ID, a new
tand signature, and the next attempt number. If attempt 7 fails, the delivery is marked as failed. A delivery also fails when the webhook is disabled or deleted before an attempt. - At least once: your endpoint may receive the same event more than once, for example when its response timed out. Use the event ID (
idin the body, or theX-IGrant-Event-Idheader) to detect duplicates. - Order: for one webhook and one subject (an issuance history, verification, held credential or presentation), an event is sent only after every earlier event of the same subject has either succeeded or finally failed. There is no ordering across subjects or webhooks. You can also sort the events of a subject by
subject.sequenceand ignore any event whose sequence you have already processed. - Delivery records: a record of each delivery, including its body, is kept for 30 days, with the event type, the status (
pending,retrying,completedorfailed), the attempt number and the status code of the last attempt. Read them with List webhook deliveries. The webhook list shows the status of the last delivery of each webhook. - Redelivery: redelivering a delivery creates a new delivery of the stored body, with a new delivery ID, attempt 1 and the same event ID. It does not wait for the other events of its subject, and they do not wait for it.
Consent Management and Data Marketplace Events
The consent management events (for example consent.allowed) and the data marketplace event (datamarketplace.data_disclosure_agreement_record) use their own body format: deliveryID, webhookID, timestamp, type and data. Their signature header is t=<UTC timestamp>,sig=<hex>, the HMAC-SHA256 of <timestamp>.<body>, and each of them is delivered in a single attempt.