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>).

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

{
  "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"
}
CODE

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

["id1", "id2", ...]
CODE

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

{
  "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
}
CODE

Informs about an state update of a connection. 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

["id1", "id2", ...]
CODE

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

["id1", "id2", ...]
CODE

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>/proofs/<proof-exchange-id>/update

{
  "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": {}
  }
}
CODE

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

["id1", "id2", ...]
CODE

Informs about the deletion of proof requests. The payload is a list of IDs of all the proof reuests that have 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.