Skip to main content

Handle notifications from GOV.UK Wallet

The credential issuer notification endpoint is an optional endpoint defined in the OID4VCI specification. GOV.UK Wallet uses this endpoint to notify you as the credential issuer of events relating to issued credentials.

GOV.UK Wallet can send notifications about events such as:

  • the credential has been successfully stored in the GOV.UK Wallet
  • the credential could not be stored in the GOV.UK Wallet because it is invalid
  • the user has taken specific actions related to the offered credential, such as declining to save it

You must include a unique notification_id parameter in each credential response for GOV.UK Wallet to be able to send notifications.

Technical details

Endpoint location

The notification endpoint’s location is implementation-specific within the OID4VCI specification.

As the credential issuer, you must publish the location of your notification endpoint in your metadata using the notification_endpoint parameter.

Request format

Your notification endpoint must accept HTTP POST requests. The request must include the:

  • Authorization header: A bearer access token, which must be a JSON Web Token (JWT), issued by GOV.UK One Login
  • JSON request body: The notification details

Request validation

Authorization header

The request must include an access token issued by the GOV.UK One Login token service as a bearer token in the Authorization header. This is the same as the access token used for authorising the issuance of a verifiable credential.

Your credential issuer must validate the access token to make sure it was issued by GOV.UK One Login and the request originates from the expected user.

To validate the access token, you must verify the signature, and validate the header parameters and payload claims.

Verify the signature
  1. Retrieve the GOV.UK One Login token service’s JSON Web Key Set (JWKS) from their published JWKS endpoint.
  2. Get the kid (key ID) parameter from the access token header.
  3. Find the matching public key in the JWKS by comparing kid values.
  4. Confirm the alg (algorithm) parameter in the token header matches the algorithm of the identified public key.
  5. Use the matching public key to cryptographically verify the token signature using the specified algorithm.
Validate the header parameters

Make sure the value of the typ (Type) parameter is "at+jwt".

Validate the payload claims

Make sure that:

  • the value of the iss (issuer) claim matches the GOV.UK One Login URL: "https://token.integration.account.gov.uk" (integration) or "https://token.account.gov.uk" (production)
  • the value of the aud (audience) claim is the credential issuer URL
  • the value of the sub (subject - this is the wallet subject identifier) claim matches the value stored in your cache for this specific credential issuance flow
  • the value of the credential_identifiers claim matches the value stored in your cache for this specific credential issuance flow
  • this API has not received another access token with the same jti (JWT ID) that is still within its validity period

Request body

The request body must be in JSON format and contain the following parameters:

Parameter Required or optional Description
event Required A case-sensitive string indicating the credential’s status.
notification_id Required A string (this could be a UUID) received in the credential response, uniquely identifying an individual credential issuance occurrence.
event_description Optional Additional information that GOV.UK Wallet may provide about the event.

The value of the event parameter must be one of the following enums:

  • credential_accepted (GOV.UK Wallet accepted the credential)
  • credential_failure (GOV.UK Wallet rejected the credential)
  • credential_deleted (user declined the credential)

Your credential issuer must validate the contents of the request body and should ignore any unrecognised parameters.

This is an example of a notification when a credential is successfully stored in GOV.UK Wallet:

{
  "notification_id": "776aefd4-26c6-4a5f-aa7c-b5e294cd87cd",
  "event": "credential_accepted",
  "event_description": "Credential has been successfully stored"
}

You can find more information about the notification request in the OID4VCI specification.

Response format

You should return a 204 No Content HTTP status code when you process a notification successfully.

If the notification could not be processed, you must return an appropriate HTTP error status code.

If the request does not include an access token or the access token is invalid, your notification endpoint must return a 401 Unauthorized status code and a WWW-Authenticate header as defined in RFC6750.

When the notification_id value is invalid, the notification endpoint must return a 400 Bad Request HTTP status code and a response body in JSON format containing the following parameter:

  • error: A case-sensitive string indicating the error - invalid_notification_id (the request’s notification_id was invalid), or invalid_notification_request (the request was invalid)

This is an example of a notification error response when the notification request included an invalid notification_id:

{
  "error": "invalid_notification_id"
}

You can find more information about the error notification responses in the OID4VCI specification.

Idempotency

There may be situations where a notification is sent more than once, for example as a result of network issues. If identical requests are made with the same notification_id then your notification endpoint must return an identical response.

This page was last reviewed on 1 December 2025. It needs to be reviewed again on 1 March 2026 .