Webhooks
EUDIPLO sends a webhook when a presentation ends, when a wallet reports what it did with an issued credential, when an operator cancels a session and when credentials are revoked with their wallet unit. This page is the reference for these payloads, for where webhooks are configured, and for how they are delivered. Claim requests during issuance use a different contract, described in the attribute provider API.
Overviewā
| Webhook | Sent when | Configured by |
|---|---|---|
| Presentation result | An OID4VP, Digital Credentials API or ISO 18013-7 presentation ends as completed or failed | Inline webhook of POST /api/verifier/offer, otherwise webhookEndpointId of the presentation configuration |
| Issuance notification | The wallet calls the OID4VCI notification endpoint | webhookEndpointId of POST /api/issuer/offer |
| Wallet unit revocation | EUDIPLO revoked credentials because their wallet unit attestation was revoked | webhookEndpointId of the credential configuration, otherwise of the offer while the session exists |
There is no event subscription model: each webhook goes to the one URL configured for that flow.
An example receiver for the notification webhook, plus an endpoint that logs any webhook it receives, is in EUDIPLO/examples.
Configure a webhookā
Webhook endpointsā
A webhook endpoint is a reusable, tenant-scoped target, managed under /api/issuer/webhook-endpoints by clients with the issuance:manage or presentation:manage role. Configurations and offers reference it by id.
{
"id": "membership-results",
"name": "Membership results",
"url": "https://backend.example.com/eudiplo/webhook",
"auth": {
"type": "apiKey",
"config": { "headerName": "x-api-key", "value": "replace-with-a-random-secret" }
}
}
| Field | Required | Description |
|---|---|---|
id | yes | Identifier within the tenant |
name | yes | Display name |
description | no | Free text |
url | yes | Target of the POST requests |
auth | yes | { "type": "none" } or the apiKey object above |
With apiKey, EUDIPLO sends value in the header named headerName. Webhook requests are not signed, so use HTTPS and check the header. In configuration files, use a ${VAR} placeholder for value (Configuration as code).
The API never returns value: webhook endpoint and attribute provider responses and session details show <redacted> instead. Send <redacted> back in a PATCH to keep the stored key. It is rejected with 400 when no key is stored, and when the same PATCH changes url: send the key again then, so that it never goes to a new address without you supplying it.
Where webhooks are referencedā
| Place | Field | Effect |
|---|---|---|
Presentation request (POST /api/verifier/offer) | webhook | Inline object with url, auth and optional includeRawTokensFor; replaces the configuration's endpoint for this request |
| Presentation configuration | webhookEndpointId | Default target for presentation results |
Credential offer (POST /api/issuer/offer) | webhookEndpointId | Target for the notifications of this issuance session and, without one on the credential configuration, for its wallet unit revocation webhook |
| Credential configuration | webhookEndpointId | Target of the wallet unit revocation webhook; notifications only go to the endpoint named in the offer |
The presentation target is resolved when the request is created; later changes to the endpoint do not affect running sessions. A webhookEndpointId that does not exist is logged as a warning and no webhook is sent; only the wallet unit revocation webhook then tries the next target.
Presentation webhookā
EUDIPLO sends one POST per presentation after the session reached its final status. The payload always contains status, outcome and session; credentials is only present when the presentation succeeded, reference only when the request set one.
Completed:
{
"status": "completed",
"outcome": {
"result": "success",
"source": "verifier",
"credentials": [
{
"id": "membership",
"verified": true,
"trust": {
"matchedIssuer": "Membership Demo",
"issuanceThumbprint": "3fā¦",
"matchMode": "ca"
}
}
]
},
"credentials": [
{
"id": "membership",
"values": [
{
"vct": "urn:example:membership:1",
"iss": "https://eudiplo.example.com/issuers/membership-demo",
"name": "Max",
"member_id": "M-001"
}
]
}
],
"session": "0b6f3a8e-6d0c-4b8e-9a63-2f1c5d7e9a10",
"reference": "order-4711"
}
Failed (here an issuer that is not on the trust list):
{
"status": "failed",
"outcome": {
"result": "failed",
"source": "verifier",
"error": "trust_chain_not_trusted",
"message": "The credential issuer is not in the trusted list.",
"credentials": [
{
"id": "membership",
"format": "dc+sd-jwt",
"verified": false,
"error": "trust_chain_not_trusted",
"message": "The credential issuer is not in the trusted list."
}
]
},
"session": "0b6f3a8e-6d0c-4b8e-9a63-2f1c5d7e9a10"
}
| Field | Description |
|---|---|
status | completed or failed |
outcome | Structured result with machine-readable error codes; see Session outcome |
credentials | Only on success. OID4VP: one entry per DCQL credential id with the disclosed claims of each presentation in values (cnf and status removed). ISO 18013-7: id, format, docType and claims |
session | Session ID, as returned by POST /api/verifier/offer |
reference | Your reference of the request; only present when set |
transaction_data | The transaction data of the request, if it had any |
A wallet that declines sends an OAuth error; the webhook then reports failed with outcome.source set to wallet, the wallet's error code (for example access_denied) as outcome.error and its error_description, if any, as outcome.description; see wallet error responses. Expired requests do not trigger a webhook.
Raw tokensā
For every DCQL credential id listed in includeRawTokensFor of an inline webhook, the matching credentials entry also contains rawToken with the presented token as received, for example the SD-JWT VC with its key binding JWT. Webhook endpoints referenced by webhookEndpointId cannot request raw tokens, and failure payloads never contain them.
Redirect overrideā
Your webhook may answer with a JSON body containing redirectUri. EUDIPLO then sends the wallet to that URI instead of the configured redirect URI, on success with response_code and on failure with error parameters appended. For ISO 18013-7, failures never redirect. How to handle the redirect is described in Receive results.
{ "redirectUri": "https://shop.example.com/checkout/done?order=4711" }
Other response fields are ignored.
Notification webhookā
When the wallet calls the notification endpoint, EUDIPLO records the event on the session, sets the session status if it is the session's first event, and then forwards the event to the webhook endpoint named in the offer. Later events of the same session are forwarded as well but leave the status alone (Issuance notifications):
{
"notification": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"event": "credential_accepted",
"credentialConfigurationId": "membership"
},
"session": "a6318799-dff4-4b60-9d1d-58703611bd23",
"reference": "order-4711"
}
| Field | Description |
|---|---|
notification.id | notification_id that EUDIPLO returned in the credential response |
notification.event | Sent by the wallet: credential_accepted, credential_failure or credential_deleted |
notification.eventDescription | The wallet's event_description; only present when the wallet sent one |
notification.credentialConfigurationId | Credential configuration of the notified credential |
session | Issuance session ID, as returned by POST /api/issuer/offer |
reference | Your reference of the offer; only present when set |
The response body is ignored.
Cancellation webhookā
When an operator cancels a pending session, EUDIPLO informs the session's webhook: the webhook passed with the presentation request, otherwise the webhook endpoint of the offer or presentation configuration.
{
"status": "cancelled",
"session": "a6318799-dff4-4b60-9d1d-58703611bd23",
"reference": "order-4711",
"reason": "sent to wrong recipient"
}
| Field | Description |
|---|---|
status | Always cancelled |
session | ID of the cancelled session |
reference | Your reference, when one was set |
reason | The reason passed when cancelling, when one was given |
The response body is ignored.
Wallet unit revocation webhookā
When the wallet unit check revokes credentials because the wallet provider revoked their wallet unit attestation, EUDIPLO sends a webhook per issuance session and credential configuration with the credentials one run revoked; a run that works through many credentials, or a later run, can send further webhooks for the same session. It goes to the webhook endpoint of the credential configuration, otherwise to the webhook endpoint of the offer, as long as the session has not been deleted. An endpoint that no longer exists is logged as a warning and the next one is tried. Without any target, nothing is sent.
{
"status": "revoked",
"reason": "wallet_unit_revoked",
"session": "a6318799-dff4-4b60-9d1d-58703611bd23",
"reference": "order-4711",
"credentialConfigurationId": "pid",
"statusEntries": [
{
"uri": "https://issuer.example/issuers/tenant-1/status-management/status-list/1b4cā¦",
"idx": 42
}
]
}
| Field | Description |
|---|---|
status | Always revoked |
reason | Always wallet_unit_revoked |
session | Issuance session of the credentials |
reference | Your reference, when one was set and the session still exists |
credentialConfigurationId | Credential configuration of the revoked credentials |
statusEntries | The status.status_list entries of the revoked credentials, as in the credentials |
The response body is ignored.
Deliveryā
- One attempt. Each webhook starts with a single
POSTwith a JSON body. EUDIPLO does not retry. - Synchronous. The wallet's request waits for your webhook, because a presentation webhook can change the redirect. Answer quickly and do slow work afterwards.
- Limits. A delivery, redirects included, ends after 60 seconds, and EUDIPLO reads at most 5 MiB of the answer. A later or larger answer counts as a failed delivery.
- Redirects. EUDIPLO follows up to 5 redirects. Each target must pass the outbound URL policy below;
307and308repeat thePOST, other redirects continue with aGETwithout body. The API key header is only sent to the origin of the webhook URL, not to a redirect target on another origin. - Presentation failures are best effort. The session status is final before the webhook is sent. A failed delivery (connection error, non-2xx status, blocked URL) is logged and changes neither the session nor the wallet's result. Use polling or the event stream as a fallback.
- Cancellation webhooks are best effort. The session is cancelled before the webhook is sent; a failed delivery is only logged.
- Wallet unit revocation webhooks are best effort. The credentials are revoked before the webhook is sent; a failed delivery is only logged and not repeated.
- Notification failures are best effort. EUDIPLO records the event and, for the session's first event, the session status before it sends the webhook. A failed delivery is logged and changes neither the session nor the answer to the wallet. The recorded events stay in
notificationsof the session. - Outbound URL policy. Webhook URLs must use HTTPS and resolve to public addresses unless
OUTBOUND_URL_ALLOW_HTTPorOUTBOUND_URL_ALLOW_PRIVATE_NETWORKallow otherwise. WithOUTBOUND_URL_ALLOWED_HOSTSset, the host must also be on that list; see environment variables. A blocked URL counts as a failed delivery.