Webhook Events

Clients can subscribe to the Webhooks of the Lissi Agent to get informed about a variety of events. As an alternative to the HTTP-based Webhook events, clients can also subscribe to Kafka or WebSocket events.

Subscribing to Webhook Events

Clients can subscribe to Webhook events via the HTTP API.

Subscribe	`POST /ctrl/api/v1.0/webhook-subscriptions/subscribe`
Unsubscribe	`POST /ctrl/api/v1.0/webhook-subscriptions/{id}/unsubscribe`

Each Webhook subscription only serves the events of one tenant. Clients can subscribe to the Webhook events of multiple tenants in order to receive events of multiple tenants. In order to know to which tenant an event belongs it is recommended to encode the tenant ID in the client's base URL (e.g. https://sample-client.com/events/<tenant-id>).

Shared topic subscription

When subscribing to Webhook events, one can specify the boolean request query parameter sharedTopic:

if set to false, the Lissi Agent will send Webhook events to the base URL, followed by the corresponding event path (e.g. /<topic>/<id>/<event>) with payload object payload;
if set to true, the Agent sends all Webhook events to the provided base URL only—not to the event path. The event path is sent as a string within the payload, which consists of a string event and an object payload. The Webhook subscriber is responsible for parsing this event and using it to interpret the payload.

Examples

With sharedTopic=false, a notification is sent to https://sample-client.com/events/<topic>/<id>/<event> with payload payload;
with sharedTopic=true, a notification is sent to the base URL https://sample-client.com/events with a payload object consisting of the same payload as above and the event path string event="/<topic>/<id>/<event>".

If not defined, the default value of sharedTopic is false.

Webhook Endpoints

The following table lists the Webhook events that are sent by the Lissi Agent to the clients.

Endpoint	Payload	Description
`<base-url>/connections/<connection-id>/update`	JSON `{ "id": "b25de7d9-1c0d-489a-82e7-f8bb1ca370cc", "createdAt": "2022-11-09T14:35:46.532657Z", "updatedAt": "2022-11-09T14:35:46.532657Z", "state": "INVITED", "myDid": null, "theirDid": null, "theirRole": "INVITEE", "myLabel": "not supported yet", "theirLabel": null, "alias": "Test", "accept": "auto" }`	Informs about an state update of a connection. The possible states are: invited requested responded complete (see also https://github.com/hyperledger/aries-rfcs/tree/main/features/0160-connection-protocol)
`<base-url>/connections/<connection-id>/delete`	`n/a`	Informs about the deletion of ONE connection. The URL paths encodes the ID of the connection that has been deleted.
`<base-url>/connections/delete`	JSON `["id1", "id2", ...]`	Informs about the deletion of connections. The payload is a list of IDs of all the connections that have been deleted.
`<base-url>/credentials/<credential-exchange-id>/update`	JSON { "id": "71f38c2d-e1b4-4d52-b99d-9a8f2cd3a557", "state": "CREDENTIAL_OFFER_SENT", "createdAt": "2022-11-09T15:40:59.080630Z", "updatedAt": "2022-11-09T15:40:59.080630Z", "schemaId": "Hd7qgjqDe7ywUojDZY7fYW:2:BaseID:2.1", "connectionId": "42fac989-f415-4b88-9095-e1e938edb634", "connectionAlias": "Test", "connectionTheirLabel": "lissi", "credDefId": "Hd7qgjqDe7ywUojDZY7fYW:3:CL:13776:Base ID", "credDefImageId": "Hd7qgjqDe7ywUojDZY7fYW:3:CL:13776:Base ID", "credDefAlias": "Base ID", "credDefActive": true }	Informs about an state update of a credential. The possible states are: proposal received credential offer sent request received credential issued (see also https://github.com/hyperledger/aries-rfcs/tree/main/features/0036-issue-credential )
`<base-url>/credentials/<credential-exchange-id>/delete`	`n/a`	Informs about the deletion of ONE credential. The URL paths encodes the ID of the credential that has been deleted.
`<base-url>/credentials/delete`	JSON `["id1", "id2", ...]`	Informs about the deletion of credentials. The payload is a list of IDs of all the connections that have been deleted.
`<base-url>/credentials/<credential-exchange-id>/revoke`	`n/a`	Informs about the revocation of ONE credential. The URL paths encodes the ID of the credential that has been revoked. Every deleted credential will also be revoked in case the credential definition used to create this credential is revocable.
`<base-url>/credentials/revoke`	JSON `["id1", "id2", ...]`	Informs about the revocation of credentials. The payload is a list of IDs of all the connections that have been revoced. Every deleted credential will also be revoked in case the credential definition used to create this credential is revocable.
`<base-url>/holder-credential/<credential-offer-id>/update`	JSON { "credentialOfferId": "23116f16-b422-4275-a301-09448e6c70a2", "connectionId": "9c5d7610-d6f8-483e-839f-9d2c09e10617", "connectionTheirLabel": "new tenant", "credentialDefinitionId": "BmT2vRWoqHCpaAL5YrvVs4:3:CL:20861:Test", "state": "CREDENTIAL_OFFER_RECEIVED", "createdAt": "2023-08-03T07:44:52.438314Z", "updatedAt": "2023-08-03T07:44:52.438314Z", "schemaId": "BmT2vRWoqHCpaAL5YrvVs4:2:New:1.0", "credentialProposalDict": { "credentialProposal": { "attributes": [ { "name": "Name", "value": "New", "mimeType": { "type": "text", "subtype": "plain", "parameters": {}, "qualityValue": 1, "charset": null, "concrete": true, "wildcardType": false, "wildcardSubtype": false, "subtypeSuffix": null } } ] } }, "revocationRegistryId": null, "revocationId": null, "defaultColor": 4 }	Informs about the state of a credential from the holder perspective. The possible states are: proposal received credential offer sent request received credential issued (see also https://github.com/hyperledger/aries-rfcs/tree/main/features/0036-issue-credential )
`<base-url>/holder-credentials/<crededential-offer-id>/delete`	`n/a`	Informs about the deletion of a credentials from an Holder perspective. The URL paths encodes the ID of the credential that has been deleted.
`<base-url>/proofs/<proof-exchange-id>/update`	JSON { "id": "4ecd3979-a534-41fd-af53-4904b277bcf3", "initiator": "self", "role": "verifier", "state": "PRESENTATION_RECEIVED", "verified": false, "indyVerified": false, "deviceBindingVerified": null, "deviceBindingVerificationStatus": null, "createdAt": "2022-11-09T15:42:32.949529Z", "updatedAt": "2022-11-09T15:44:06.758812Z", "connectionId": "42fac989-f415-4b88-9095-e1e938edb634", "connectionAlias": "Test", "connectionTheirLabel": "lissi", "proofTemplateId": "bd48ca41-82fa-4e68-80eb-6b280f78d7c1", "proofTemplateName": "ProofForBaseId", "proofTemplateImageId": "bd48ca41-82fa-4e68-80eb-6b280f78d7c1", "proofTemplateActive": true, "presentation": { "revealedAttributes": { "Hd7qgjqDe7ywUojDZY7fYW:3:CL:13776:Base ID": [ { "name": "Address city", "value": "Frankfurt" } ] }, "selfAttestedAttributes": [ { "name": "Name", "value": "Test" } ], "predicates": {} } }	Informs about an state update of a proof request. The possible states are: request sent proposal received request received presentation received (see also https://github.com/hyperledger/aries-rfcs/tree/main/features/0037-present-proof)
`<base-url>/proofs/<proof-exchange-id>/delete`	`n/a`	Informs about the deletion of ONE proof request. The URL paths encodes the ID of the proof request that has been deleted.
`<base-url>/proofs/delete`	JSON `["id1", "id2", ...]`	Informs about the deletion of proof requests. The payload is a list of IDs of all the proof reuests that have been deleted.
`<base-url>/holder-proofs/<proof-exchange-id>/update`	JSON { "id": "a2bf1391-889b-43d8-a3ae-a445ee827b34", "connectionId": "9c5d7610-d6f8-483e-839f-9d2c09e10617", "theirLabel": null, "alias": null, "initiator": "EXTERNAL", "role": "PROVER", "state": "REQUEST_RECEIVED", "presentationRequest": { "version": "1.0", "name": "proof", "requestedAttributes": { "attrGrp_0": { "name": null, "names": [ "Name" ], "nonRevoked": null, "restrictions": [ { "credDefId": "BmT2vRWoqHCpaAL5YrvVs4:3:CL:20861:Test", "schemaId": null } ] } }, "requestedPredicates": {}, "nonRevoked": null }, "presentation": null, "verified": null, "indyVerified": null, "createdAt": "2023-08-03T09:42:54.817773Z", "updatedAt": "2023-08-03T09:42:54.817773Z" }	Informs about an state update of a proof request from the holder perspective. The possible states are: request sent proposal received request received presentation received (see also https://github.com/hyperledger/aries-rfcs/tree/main/features/0037-present-proof)
`<base-url>/holder-proofs/<proof-exchange-id>/delete`	`n/a`	Informs about the deletion of a proof request from an holder perspective. The URL paths encodes the ID of the proof request that has been deleted.

Authentication

To authenticate the Webhook calls, the Lissi Agent includes the header X-API-Key in all the requests sent to the clients. The API key is defined when subscribing to the Webhook events.

Failure Handling

In case a client is not available when an event is sent out the event will be lost. Currently, there is no retry mechanism in place. The Lissi Agent will log an error in case it failed to send any Webhook event to a subscribed client.