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:

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*",
    "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.

• 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",
    "requestId": "...",
    "presentation": "...",
}

Fields

• requestId - unique identifier of the issuance 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

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