1. REST API for Oracle Blockchain Platform on Oracle Cloud Infrastructure (Hyperledger Fabric v2.5)
  2. Tasks
  3. Application Operations
  4. Hyperledger Fabric v2.5
  5. Events

Subscribe to an Event

post

/restproxy/api/v2/channels/{channelName}/event-subscriptions

Subscribe to an event.

Request

Supported Media Types
Path Parameters
Body ()
Request to subscribe to an event
Root Schema : EventSubscription
Type: object
Show Source
Nested Schema : callbackTLSCerts
Type: object
TLS certificate information
Show Source
Nested Schema : oauth
Type: object
Provide details of the OAuth application if the callback server is OAuth2 protected. Only client credential and refresh token flows are supported.
Show Source
Nested Schema : scopes
Type: array
List of scopes to be associated with the token.
Show Source
Back to Top

Response

Supported Media Types

200 Response

Successful operation
Body ()
Root Schema : schema
Type: object
Show Source
Nested Schema : result
Type: object
Show Source

400 Response

Bad Request

401 Response

Not authorized

403 Response

Forbidden

404 Response

Invalid parameters

500 Response

Service unavailable
Back to Top

Examples

This endpoint is used to request an event subscription.

Invoking Callback Endpoints with TLS Certs

The following example shows how to request an event subscription by submitting a POST request on the REST resource using cURL. 

curl -v -u <username>:<password> -X POST \
  "https://<restproxy of your Blockchain instance>/api/v2/channels/<channelName>/event-subscriptions" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data @<JSON file with the request parameters>

For example, 

curl -v -u obpuser:<password> -X POST \
  "https://myvm.oracle.com:10000/restproxy/api/v2/channels/default/event-subscriptions" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  --data @file.json
The contents of file.json are: 
{
 "role": "myinstance_defaultuser",
 "type": "chaincode",
 "callbackURL": "http://192.0.2.1:9000",
 "expires": "1m", 
 "callbackTLSCerts": { 
   "caCert": "",
   "clientCert": "",
   "keyPassword": "" },
 "txid": "b1c11242383212cfdcca97d68efc0b3641436b1845a9b4c6e822cf6099ca49ee",
 "chaincode": "obcs-example02",
 "seek": "oldest", 
 "block": 0,
 "event": ".*",
 "oauth": {}
}

What each parameter in the payload file represents:

Table - Payload Parameters

Parameter Purpose Possible Values
role Name of the Fabric enrollment to be used.  
type Event type
  • transaction: concerned with events on a particular transaction ID.
  • chaincode: returns events emitted from a chaincode.
  • block: returns the entire data in a block.
  • filteredblock: returns block number and each transaction ID along with the validation code and payload of the chaincode event.
callbackURL Event callback address. Must be a valid HTTP/HTTPS address.
maxCallbackRetry This parameter tells the system how many times to keep retrying the call until event delivery succeeds or until the REST proxy restarts.

The retry interval will exponentially increase, starting at 1s and increasing to 120s.

An HTTP 4XX response (excluding HTTP 401 and HTTP 429) will override this value as they're considered to be terminal failures. The system will log that particular event as a failure, and proceed with any remaining events in the queue.

 Must be an integer. Represents the number of times to retry after the initial call.

The default is 7.
expires Subscribed event expire time since the time of current request.
  • <xx>M, <xx>w, <xx>d, <xx>h, <xx>m where:
    • xx is a valid integer.
    • M represents month.
    • w is week.
    • d is day.
    • h is hour
    • m indicates minute.
  • If not set, default value is 1d, that is, one day.
callbackTLSCerts Call back TLS Certificates. It contains:
  • caCert (optional): Callback server's CA certificate. It will be used by Rest Proxy to verify the callback server. The certificate must be in PEM format.
  • clientCert (optional): Client certificate that will be used as Rest Proxy's certificate when connecting to the callback server. It is 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.
  • keyPassword (optional): Encrypted private key's password. It must be base64 encoded and it is required only when the clientCert contains an encrypted private key.
txid Transaction ID  
chaincode Chaincode ID of the chaincode application subscribed to.  
seek Which blocks to be delivered.
  • oldest: delivers all blocks from the oldest block
  • newest: delivers the newest block
  • from: delivers from the block number specified for the block parameter.

This option can be used for all parameter type except transaction.

block Block number This value is used when seek is from.
event Chaincode's event filter * specifies all events.

Note:

You can find the REST proxy value of your Blockchain instance from the Nodes tab of your instance console.

The maximum payload size of an event is limited to 50 KB. Any events larger than the maximum payload size will be dropped. The Oracle DevOps team can modify this parameter by request. If you expect to subscribe to events where the payload will be larger than 50 KB, open a Service Request (SR) in My Oracle Support to request a larger maximum event size.

Invoking Callback Endpoints Secured with OAuth 2.0

You can invoke callback endpoints secured with OAuth 2.0. In this case you pass the oauth parameter instead of the callbackTLSCerts parameter. The following example shows a payload file for event subscription using OAuth 2.0 tokens: 
{
  "type": "block",
  "callbackURL": "192.0.2.1",
  "callbackTLSCerts": {},
  "expires": "30m",
  "seek": "newest",
  "event": ".*",
  "maxCallbackRetry": 7,
  "oauth": {
      "clientID": "my-client-id",
      "clientSecret": "my-client-secret",
      "tokenUrl": "https://identity.example.com/oauth2/v1/token",
      "authInHeader": true,
      "scopes": ["urn:opc:idm:__myscopes__"]
  }
}
Where:
  • type specifies the event type. In this example, block indicates that the data from a block will be returned.
  • callbackURL specifies the event callback address which is a valid HTTP/HTTPS address.
  • expires indicates that this subscription expires after 30 minutes since the time of current request.
  • seek specifies which blocks to be delivered. In this example, newest indicates that this subscription delivers the newest block. This option can be used for all parameter type except transaction.
  • event is the chaincode event filter. * indicates that the user subscribed to all the events in the specified chaincode.
  • maxCallbackRetry specifies the number of times event delivery is attempted until it succeeds. The default value of the maxCallbackRetry parameter is 7.

The oauth parameter contains the following parameters:

Table - OAuth Parameters

Parameter Purpose
clientID The client ID. Required when using client credentials. Optional when refreshing an expired token.
clientSecret The client secret. Required when using client credentials. Optional when refreshing an expired token.
refreshToken The refresh token. Required when refreshing the use of an access token that has expired.
tokenUrl The URL to use to obtain tokens. This parameter is always required.
scopes A list of scopes to associate with the token.
authInHeader A Boolean value indicating how the credentials will be passed. If true, the credentials will be passed in the header using basic authentication. If false, the credentials will be passed in the payload.

Example of the Response Body

The following example shows the contents of the response body in JSON format:

{
   "returnCode": "Success",
   "error": "",
   "result": {
       "subid": "obpuser-dc28b77c-7e58-4b09-ae23-b2c01fa01b70"
   }
}
Back to Top