Inbound webhooks

When certain components are missing during the recipe printing process, Document Rails may communicate with configured inbound webhooks for additional data.

Inbound webhooks may receive requests for input credentials, credential subject identifiers, or output credential identifiers.

External user identifiers

To the utilize inbound webhook functionality, users have to provide external user identifiers.

These identifiers are opaque string values, that Document Rails passes as-is to your inbound webhook. You can utilize external user identifiers to perform user-specific data lookups.

Good examples of external user identifiers include user emails, unique numeric identifiers, etc.

OID4VCI access token

Some request types may include the accessToken field, which contains the original access token passed from the wallet used to request the OID4VCI credential issuance.

Your application may choose to validate the access token to make sure the user can actually request the credential issuance.

OID4VCI issuer state

If the issuer_state value is passed from the wallet, Document Rails will propagate it into all inbound webhook requests to let your implementation know about the request context.

For example, issuer_state may be used to carry the context string across the entire OID4VCI issuance flow, allowing your server to select data or run arbitrary actions depending on the value.

Protocol

Webhook communication is performed via HTTPS with a 10 second timeout.

During the communication process, Document Rails will always provide the following headers:

Request body is a JSON object with the following basic structure:

{
    "type": "...",
}

Using the type field, you can determine the received request type.

Supported inbound webhook request types:

Input credential request

Document Rails may send this request if the input credential required for the printing process is missing.

Request structure

Input credential requests have the following body structure:

{
    "type": "credential",
    "credentialKind": 2,
    "credentialType": "ExampleCredential",
    "recipeId": "6bf0188d-5103-4403-9471-6a1a5a15d411",
    "requestId": "99a2e16e-2903-4b9c-9627-c55cfbc9a840",
    "userId": "external.user.id@example.com",
    "accessToken": "...",
    "issuerState": "..."
}

Response structure

Inbound webhook response should adhere to the following structure:

{
    "credential": ...
}

The credential field should include the input credential.

Credential subject identifier request

Requests of this type are sent when Document Rails lacks information about the credential subject identifier (user wallet DID, JWK, etc.).

Request structure

Credential subject identifier requests adhere to the following structure:

{
    "type": "credentialSubject",
    "credentialKind": 2,
    "recipeId": "6bf0188d-5103-4403-9471-6a1a5a15d411",
    "requestId": "99a2e16e-2903-4b9c-9627-c55cfbc9a840",
    "userId": "external.user.id@example.com",
    "accessToken": "...",
    "issuerState": "..."
}

Response structure

Inbound webhook response should adhere to the following structure:

{
    "credentialSubject": ...
}

The credential_subject field should include the credential subject identifier.

Output credential identifier request

If the information about the output credential identifier is missing, Document Rails may send a request of this type to your server to acquire it.

Request structure

Requests of this type adhere to the following structure:

{
    "type": "credentialIdentifier",
    "credentialKind": 2,
    "recipeId": "6bf0188d-5103-4403-9471-6a1a5a15d411",
    "requestId": "99a2e16e-2903-4b9c-9627-c55cfbc9a840",
    "userId": "external.user.id@example.com",
    "accessToken": "...",
    "issuerState": "..."
}

Response structure

Inbound webhook response should adhere to the following structure:

{
    "credentialIdentifier": "ExampleIdentifier"
}