Skip to main content

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:

APIDescriptionDocumentation
Create WebhookCreate a webhook endpoint and subscribe to event typesCreate Webhook
Read WebhookGet the details of a webhookRead Webhook
Update WebhookReplace the configuration of a webhookUpdate Webhook
Delete WebhookRemove a webhook endpointDelete Webhook
List WebhooksGet all the webhooks, with the status of the last delivery of each webhookList Webhooks
Ping WebhookCheck that the payload URL respondsPing Webhook
Read webhook event typesGet the event types that a webhook of your organisation can subscribe toRead webhook event types
List webhook content typesGet the payload content types (only application/json)List webhook content types
List webhook deliveriesGet the deliveries of a webhook, with the status of each deliveryList webhook deliveries
Read webhook deliveryGet one delivery of a webhookRead 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 typesFeature
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 403 with errorKey feature_disabled. A new event type of a service that the installation does not have gets 400 with errorKey service_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 typeMeaning
ows.issuer.issuance_history.createdA 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_retrievedThe wallet fetched the credential offer for the first time.
ows.issuer.issuance_history.token_issuedThe 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_suppliedYou provided the claims of a deferred issuance history.
ows.issuer.issuance_history.credential_deferredThe 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_issuedThe issuer signed and returned the first credential of the issuance history, including all its batch copies.
ows.issuer.issuance_history.credential_reissuedThe issuer signed and returned a new version of the credential of the issuance history.
ows.issuer.issuance_history.credential_acceptedThe wallet told the issuer that it accepted the credential.
ows.issuer.issuance_history.credential_deletedThe 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_failedThe wallet told the issuer that it could not store or use the credential.
ows.issuer.issuance_history.deniedThe 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.revokedThe 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.expiredThe 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.deletedYou 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 typeMeaning
ows.verifier.verification.createdA new verification has started: the verifier created a presentation request.
ows.verifier.verification.request_retrievedThe wallet fetched the presentation request for the first time.
ows.verifier.verification.presentation_receivedThe wallet sent a presentation and the verifier checked it. data.verification.isVerified holds the result.
ows.verifier.verification.declinedThe 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.revalidatedYou revalidated the received presentation. data.verification.isVerified holds the result.
ows.verifier.verification.deletedYou 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 typeMeaning
ows.holder.credential.createdThe 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.receivedThe holder wallet received the credential from its issuer.
ows.holder.credential.reissuedThe holder wallet received a new version of the credential from its issuer.
ows.holder.credential.acceptedYou accepted the held credential.
ows.holder.credential.revokedA status check found that the issuer revoked the held credential.
ows.holder.credential.suspendedA status check found that the issuer suspended the held credential.
ows.holder.credential.reactivatedA status check found that the issuer made a revoked or suspended held credential valid again.
ows.holder.credential.deletedYou deleted the held credential.
ows.holder.presentation.request_receivedThe holder wallet received a presentation request.
ows.holder.presentation.sentThe holder wallet sent the presentation to the verifier.
ows.holder.presentation.deletedYou 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.

FieldTypeDescription
idstringThe event ID, a lower-case UUID. Use it to detect duplicates.
typestringThe event type, for example ows.issuer.issuance_history.credential_issued.
schemaVersionintegerThe 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.
occurredAtstringThe time of the step, in RFC 3339 format in UTC (for example 2026-11-05T08:00:00Z).
organisationIdstringThe ID of your organisation. For an event of a sandbox organisation, this is the ID of the main organisation.
sandboxOrganisationIdstring or nullThe ID of the sandbox organisation, or null for the main organisation. Always present.
subjectobjectThe 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.
dataobjectA 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.

FieldTypeDescription
credentialExchangeIdstringThe credential exchange ID, which is the ID of the issuance history.
credentialDefinitionIdstring or nullThe ID of the credential definition.
credentialConfigurationIdstring or nullThe ID of the credential configuration.
formatstring or nullThe credential format, for example dc+sd-jwt or mso_mdoc.
modestringin_time or deferred.
originstringHow 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).
offerIdstring or nullThe ID of the credential offer. The issuance histories of one offer have the same offerId.
statusstringoffer_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.
revokedAtstring or nullThe time of the revocation, or null when the issuer did not revoke the credentials.
individualIdstring or nullThe ID of the individual.
clientIdstring or nullThe client identifier of the wallet.
reissueCountintegerThe number of times that the issuer re-issued the credential.
createdAtstringThe time when the issuance history was created.
updatedAtstringThe time of the last change of the issuance history.
issuedAtstring or nullThe time when the issuer issued the first credential.
lastReissuedAtstring or nullThe 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:

FieldEventsDescription
credentialcredential_issued, credential_reissued, credential_accepted, credential_deleted, credential_failedThe 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.
granttoken_issuedpre_authorised_code, authorisation_code or refresh_token.
revokedcredential_deletedtrue when the issuer revoked the credential in the same step.
reasondenied, credential_failed, revokedAn object with code and description (see the reason table below).
credentialsrevokedUp 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).
credentialCountrevokedThe 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:

FieldTypeDescription
idstringThe ID of the issued credential.
versionintegerThe version of the credential: 1 for the first credential, and one more for each re-issuance.
copiesintegerThe number of batch copies of this version (1 without a batch).
issuedAtstringThe time when the issuer issued this version.
validUntilstring or nullThe end of the validity of this version, or null when it has no end.
holderKeyChangedbooleantrue when the holder key of this version is not the key of the previous version.

The values of data.reason:

Eventcodedescription
deniedThe error ID, for example issuance.wallet_attestation_not_verified.The description of the error.
credential_failedwallet.credential_failureThe text that the wallet sent, at most 500 characters.
revokedrevocation_requested, for a revocation through the API.The reason of the request, or an empty text.
revokedorganisation_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:

FieldTypeDescription
idstringThe ID of the verification.
presentationDefinitionIdstring or nullThe ID of the presentation definition.
statusstringrequest_sent, request_received or presentation_acked.
isVerifiedbooleantrue when the verifier verified the presentation.
responseModestring or nullThe response mode of the presentation request, for example direct_post.jwt.
credentialExchangeIdstring or nullThe credential exchange ID of the issuance history of a dynamic credential request.
individualIdstring or nullThe ID of the individual.
dataAgreementIdstring or nullThe ID of the data agreement.
createdAtstringThe time when the verification was created.
updatedAtstringThe time of the last change of the verification.

The declined event also has data.reason:

FieldDescription
codewallet.<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.
descriptionThe 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:

FieldTypeDescription
idstringThe ID of the held credential.
credentialFormatstring or nullThe credential format, for example dc+sd-jwt.
credentialConfigurationIdstring or nullThe ID of the credential configuration at the issuer.
credentialIssuerstring or nullThe identifier of the credential issuer.
credentialStatusstring or nullcredential_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).
revocationStatusstring or nulloperational, revoked, suspended or null.
isWalletUnitAttestationbooleantrue when the credential is a wallet unit attestation.
batchIdstring or nullThe ID of the batch of the credential.
refreshCountintegerThe number of times that the issuer re-issued the credential.
createdAtstringThe time when the held credential was created.
updatedAtstringThe time of the last change of the held credential.
issuedAtstring or nullThe time when the issuer issued the credential.
lastRefreshedAtstring or nullThe time of the last re-issuance.

The ows.holder.presentation.* events have data.presentation, a summary of the presentation:

FieldTypeDescription
idstringThe ID of the presentation.
statusstringpresentation_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.
clientIdstring or nullThe client identifier of the verifier.
clientMetadataobjectclientName: the name of the verifier, or null.
createdAtstringThe time when the presentation was created.
updatedAtstringThe 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​

HeaderDescription
Content-Typeapplication/json.
X-IGrant-Event-IdThe event ID (id of the body).
X-IGrant-Event-TypeThe event type (type of the body).
X-IGrant-Webhook-IdThe ID of the webhook.
X-IGrant-Delivery-IdThe ID of the delivery of this event to this webhook. All attempts of a delivery share the same ID.
X-IGrant-Delivery-AttemptThe attempt number, from 1 to 7.
X-IGrant-Signaturet=<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:

  1. Extract t and v1 from the header.
  2. Reject the request if t is more than 5 minutes away from your clock.
  3. Get the raw request body as bytes. Do not parse it and encode it again.
  4. Compute the HMAC-SHA256 of t + "." + body using your webhook's secret key, and encode it as lower-case hexadecimal.
  5. Compare the result with v1 in 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​

  1. Always verify the webhook signature before processing the body.
  2. Reject a t that is more than 5 minutes away from your clock, to prevent replay attacks.
  3. Keep your webhook secret key secure and never share it.
  4. Use HTTPS endpoints for webhook delivery.
  5. Respond quickly with a 2xx status code, and process the event after you have responded.

Delivery​

  • Success: only a 2xx response within 10 seconds counts as a success. Redirects are not followed, and a 3xx, 4xx or 5xx response, 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 t and 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 (id in the body, or the X-IGrant-Event-Id header) 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.sequence and 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, completed or failed), 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.

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.