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

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://10.168.108.17:9000",
 "expires": "1m", 
 "callbackTLSCerts": { 
   "caCert": "",
   "clientCert": "",
   "keyPassword": "" },
 "txid": "b1c11242383212cfdcca97d68efc0b3641436b1845a9b4c6e822cf6099ca49ee",
 "chaincode": "obcs-example02",
 "seek": "oldest", 
 "block": 0,
 "event": ".*"
}

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.

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 only if the type is block or filteredblock.

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.

Retrying Callbacks

Event delivery is attempted a number of times, specified by the maxCallbackRetry parameter, until event delivery succeeds. The default value of the maxCallbackRetry parameter is 7.

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