Outbound webhooks

To retrieve information about printed resources and output credentials, you have to configure Document Rails to upload information about the finished printing process to an external server.

Outbound webhooks receive information about printed resources, output credentials and external user identifiers, allowing your application to implement programmatic handlers for issuance events and potentially passing output credentials to holders through protocols like OID4VCI.

Authentication

Optionally, you may provide the outbound_webhook_key to automatically sign all outbound webhook requests.

If the outbound_webhook_key value is configured, you may use the following headers to verify all requests:

Primary outbound webhooks

By default, the response of outbound webhooks is not taken into account when issuing credentials. While in most applications this is acceptable, for some use-cases you may prefer to terminate the issuance process if the outbound webhook cannot be reached or if the response from it indicates an error.

This can be achieved by using primary outbound webhooks. At most one outbound webhook can be selected as the primary one for a recipe.

Primary outbound webhooks are prioritized over all other outbound webhooks, and if the response from the primary outbound webhook contains an erroneous status code, the issuance is terminated and all other webhooks are notified about the failure.

Requests

Outbound webhook communication is performed via HTTPS with a 10 second timeout.

To indicate the request type and outcome, Document Rails utilizes the outcome field.

Successful issuance

Successful issuance outbound requests utilize the following CBOR structure:

{
    "outcome": "success",
    "requestId": "...",
    "resource": "*byte sequence*",
    "oid4vciResponse": "*encoded response*",
    "accessToken": "...",
    "issuerState": "...",
    "outputCredentials": [...],
    "externalUserIds": ["ExampleId1", "ExampleId2"],
}

Fields

• requestId - unique identifier of the issuance request.

• resource - resource with the issued C2PA claim embedded within it. null or missing if the resource generation is not applicable to the recipe.

• oid4vciResponse - encoded OID4VCI response that either will be presented to the wallet by Document Rails in case of the regular issuance flow, or should be presented by your application in case of the application-delegated flow.

• accessToken - authorization server access token used within the OID4VCI issuance session. If authorization service proxy functionality was used within the issuance session, the access token reflected within the field contains the value acquired from the proxied authorization service.

• issuerState - issuer state value associated with the OID4VCI issuance session, if any.

• outputCredentials - array of JSON-encoded strings that represent the information about issued credentials, including status list identifiers.

• externalUserIds - array of external user identifiers that were utilized for the issuance transaction.

Successful presentation

Successful OID4VP presentations result in the following outbound request:

{
    "outcome": "presentation",
    "oid4vpPresentationId": "...",
    "presentation": "...",
}

Fields

• oid4vpPresentationId - unique identifier of the presentation request.

• presentation - JSON-encoded string that represents the presentation data.

Failure

These outbound requests are sent when either issuance or presentation flows fail.

{
    "outcome": "failure",
    "requestId": "...",
    "message": "Error message",
}

Fields

• requestId - unique identifier of the issuance request or an OID4VP presentation.

• message - description of the occured error.

Responses

By default, outbound webhook responses are ignored by Document Rails, including responses with non-success status codes.

If an outbound webhook is selected as the primary one, the issuance will be terminated if the response contains a non-success status code, or if the webhook cannot be reached entirely.