Event Subscribe

post

/{restproxy}/bcsgw/rest/v1/event/subscribe

Use this endpoint to subscribe to an event.

Request

Supported Media Types
Path Parameters
Body ()
Root Schema : GWRequestSubscribe
Type: object
Show Source
Nested Schema : subRequests
Type: array
Show Source
Nested Schema : GWSubReq
Type: object
Show Source
Nested Schema : GWCallbackTlsCerts
Type: object
Show Source
Back to Top

Response

Supported Media Types

200 Response

OK
Body ()
Root Schema : GWResponseSubscribe
Type: object
Show Source
Nested Schema : responses
Type: array
Show Source
Nested Schema : GWResponseList
Type: object
Show Source
Nested Schema : GWUnsubReq
Type: object
Show Source
Nested Schema : GWUnsubResponse
Type: object
Show Source

401 Response

Unauthorized

403 Response

Forbidden

503 Response

Service unavailable

Default Response

Unexpected error
Body ()
Root Schema : errorModel
Type: object
Show Source
Back to Top

Examples

With this REST API, you can call a transaction asynchronously and then get notification using an event-based approach. A REST proxy client can subscribe to Hyperledger Fabric events, and the REST proxy will push the events back to the client callback address by an HTTP/HTTPS POST request when the event is received from Hyperledger Fabric.

Limitations:
  • You can only subscribe to events via a REST proxy entity within the founder instance - not to participants in the network. This is due to the REST proxies using Kafka to handle events and non-founder instances don't have Kafka running.
  • In a network with multiple organizations, the REST proxy client can only receive events from the organization the REST proxy belongs to; the REST proxy can't join other organizations to get events.
  • Generally, events are channel-based, so the REST client (which has to be in the founder???s IDCS tenancy), should not care about the organization if the current organization is in the channel. For example, if a channel has 3 organizations (founder, participant 1 and participant 2), then the events should be available to all 3; the REST client shouldn't care which organization of the 3 organizations the event belongs to. However, if the channel has only 2 organizations (participant 1 and participant 2), then the REST client has no way to get the events of this channel.
  • If the founder organization is in a channel, but the founder doesn't have any peers in this channel, the REST proxy of the founder can invoke or query this channel (via the peers of participant 1 and participant 2), but can't get any events of this channel despite the founder being in this channel. This is a known limitation with no current workaround.
This REST API allows you to subscribe to the following events:
  • transaction: concerned with events on a particular transaction ID
  • txOnChannel: returns a transaction object for every new transaction on a particular channel
  • txOnNetwork: returns a transaction object for every new transaction in the entire network
  • blockOnChannel: returns a block header for every new block on a particular channel
  • blockOnNetwork: returns a block header on creation of a new block in the entire network
  • chaincodeEvent: returns events emitted from chaincode

The following example shows how to query the status of a transaction a by submitting a POST request on the REST resource using cURL.

curl -u <username>:<password> -X POST\
 https://<rest_server_url:port/restproxy#>/bcsgw/rest/v1/event/subscribe

Example of Request Body

The following example shows the contents of a request body in JSON format for a transaction-based event subscription:

{
  "requests": [
    {
      "eventType": "transaction",
      "callbackURL": "https://10.182.53.155:8008/client/event/transaction",
      "callbackTlsCerts": {
          "caCert": "-----BEGIN CERTIFICATE-----\....\n-----END CERTIFICATE-----",
          "clientCert": "-----BEGIN CERTIFICATE-----\....\n-----END CERTIFICATE-----\n-----BEGIN ENCRYPTED PRIVATE KEY-----\....\n-----END ENCRYPTED PRIVATE KEY-----\n",
          "keyPassword": "T3JhY2xl"
        },
      "expires": "1m",
      "txid": "69261f210bb4ed4463435c5d447e33a308d1b49e8d163dff6767b73acebae81b"
    }
  ]
}

The following example shows the contents of a request body in JSON format for an event subscription for transactions on a specified channel:

{
  "requests": [
    {
      "eventType": "txOnChannel",
      "callbackURL": "https://10.182.53.155:8008/event/txOnChannel/ch1",
      "callbackTlsCerts": {
          "caCert": "-----BEGIN CERTIFICATE-----\....\n-----END CERTIFICATE-----",
          "clientCert": "-----BEGIN CERTIFICATE-----\....\n-----END CERTIFICATE-----\n-----BEGIN ENCRYPTED PRIVATE KEY-----\....\n-----END ENCRYPTED PRIVATE KEY-----\n",
          "keyPassword": "T3JhY2xl"
        },
      "expires": "1m",
      "channel": "ch1"
    }
  ]
}

The following example shows the contents of a request body in JSON format for an event subscription for a chaincode event:

{
  "requests": [
    {
      "eventType": "chaincodeEvent",
      "callbackURL": "https://10.182.53.155:8008/event/chaincodeEvent/cc1/evtsender1",
      "callbackTlsCerts": {
          "caCert": "-----BEGIN CERTIFICATE-----\....\n-----END CERTIFICATE-----",
          "clientCert": "-----BEGIN CERTIFICATE-----\....\n-----END CERTIFICATE-----\n-----BEGIN ENCRYPTED PRIVATE KEY-----\....\n-----END ENCRYPTED PRIVATE KEY-----\n",
          "keyPassword": "T3JhY2xl"
        },
      "expires": "1m",
      "chaincode": "mycc",
      "eventName": "evtsender1",
      "payloadType":"JSON"
    }
  ]
}
requests This is an array of subscription requests. Each value is one event subscription request.
eventType Specify the event type. Options are:
  • transaction: concerned with events on a particular transaction ID.
  • txOnChannel: returns a transaction object for every new transaction on a particular channel.
  • txOnNetwork: returns a transaction object for every new transaction in the entire network.
  • blockOnChannel: returns a block header for every new block on a particular channel.
  • blockOnNetwork: returns a block header on creation of a new block in the entire network.
  • chaincodeEvent: returns events emitted from chaincode.
callbackURL The event callback URL, which must be a valid HTTP/HTTPS address.
callbackTlsCerts The TLS certificate information required for the callback.
  • caCert: the callback server's CA certificate; used by the REST proxy to verify the callback server. The certificate must be in PEM format.
  • clientCert: (optional) client certificate; used as the REST proxy's certificate when connecting to callback server. Only required when the callback server enables mutual authentication. The certificate must be in PEM format, and assumes the private key and the client certificate concatenated (similar to the option "--cert" in cURL). If you have a PKCS#12 format certificate, you can convert it to PEM format using the Linux command openssl pkcs12 -in client.p12 -out client.pem.
  • keyPassword: (optional) encrypted private key's password. Should be base64 encoded. Only required when the clientCert contains an encrypted private key.
expires
Specifies the time until the event subscription expires. Valid values (where xx is an integer):
  • xxM: months
  • xxw: weeks
  • xxd: days
  • xxh: hours
  • xxm: minutes

Optional. If it is not specified the default is one day.

channel Channel name.
chaincode Chaincode name.
eventName Specify the event name.
payloadType Specify the callback event payload type sent to the callback URL.
  • JSON: if the content of the payload is a valid JSON object or array, the object or array will be returned in the response. For example:"payload":{"type":"JSON","data":{"aaa":333}}

    If the content of the payload is not a valid JSON object or array, setting payloadType to JSON has no effect; the behavior is the same as setting payloadType to String.

  • String: returns a JSON string. If the response payload is a valid UTF-8 sequence the JSON string will be returned encoded as UTF-8. Otherwise base64 encoding is used and the base64 encoded result is returned. For example:"payload":{"type":"UTF-8","data":"{\"aaa\": 333}"}
The default behavior is String.
txid Transaction ID.

Example of Response Body

The following example shows the contents of the response body in JSON format of a successful status request:

{
  "responses": [
    {
      "request": {
        "eventType": "transaction",
        "callbackURL": "https://10.182.53.155:8008/client/event/transaction",
        "callbackTlsCerts": {
          "caCert": "-----BEGIN CERTIFICATE-----\....\n-----END CERTIFICATE-----",
          "clientCert": "-----BEGIN CERTIFICATE-----\....\n-----END ENCRYPTED PRIVATE KEY-----\n",
          "keyPassword": "T3JhY2xl"
        },
        "expires": "1m",
        "txid": "69261f210bb4ed4463435c5d447e33a308d1b49e8d163dff6767b73acebae81b"
      },
      "response": {
        "returnCode": "Success",
        "subid": "6364f9f8-5a75-4020-a2e8-7f8c8cdfdca1"
      }
    }
  ]
}
returnCode The status of the transaction is returned:
  • Success means the event subscription has completed successfully.

  • Failure means the event subscription did not complete.

subid

The subscription ID. This can be used to unsubscribe from the event.

Back to Top