Webhook Setup

Introduction

Startbahn offers integration messages on events happening on your Licensed User Wallet via webhooks.

A webhook is an HTTP POST call to an endpoint of your choice. To authenticate the call, Startbahn will send a secret API Key in the HTTP Header ‘x-api-key’. The System expects your endpoint to respond with a success code 2xx.

Note that, in case of no response from the configured endpoint or HTTP error codes such as 4xx and 5xx, the system retries up to a desired number of times (maximum 5). After all of the retries have failed, Startbahn sends an informational email to a configurable admin email address (which can be different from your regular user addresses), containing the data in a CSV format, and will not continue to send the same data again.

You can get subscribed to webhooks. Currently, the webhook subscriptions are not available for self-service, but the Startbahn team can subscribe you to the desired webhook events outlined in the following chapters and configure your API key and URL endpoint.

Webhook Details

Please note that we may add a new field. So make sure that your implementation can support accepting new fields without breaking your implementation. In case we remove the field, we will deprecate it first and let you know beforehand.

The following chapters provide details about the webhook events you can subscribe to.

Generic Parameter Details

* indicates that the field will always exist from Startbahn side.

Parameter	Webhook Type	Description	Format
type*	All	The type of the webhook	ENUM consists of transfer_key , transfer_complete, issue_complete
version*	All	The version of the webhook.	number
data*	All	The data related to the webhook that client’s need to process.	Array
data[*].groupId*	All	This groupId may not be really important for client. String to identify the grouping. Webhook data payload with same group ID will be sent to client in 1 batch.	string

SRR Related

Generic SRR Related Parameter

Additional from Generic Parameter Details, these fields exist in webhook payload of all events related to SRR.

Parameter	Webhook Type	Description	Format
data[*].srrId*	All	SRR Token ID	string
data[*].metadata*	All	Metadata of the SRR	Object
data[*].metadata.digest*	All	Digest of the metadata	string
data[*].metadata.json*	All	JSON of the metadata. Details	Object
data[*].metadata.cid	All	CID of the SRR metadata in IPFS. Refer to CID Documentation	string
data[*].metadata.createdAt*	All	Date of the metadata creation	Datetime
data[*].metadata.updatedAt*	All	Date of the metadata update if any.	Datetime

Webhook Event: Issuance of SRR completed

Subscription Name

issueComplete

Trigger

After an SRR has been minted, the subscribed issuer receives this notification

Content

An array of data for the issued SRR where each entry consists of the metadata, srrId and an optional externalId as provided by the issuer when using the CommerceAPI.

• Parameter Details * indicates that the field will always exist from Startbahn side.

  Parameter	Webhook Type	Description	Format
  data[*].srrCid	issueComplete	CID of the SRR metadata in IPFS. Refer to CID Documentation	string
  data[*].externalId	issueComplete	ID of the SRR on the client’s system that is used when calling the Issue API.	string
• Content Example

  {
     "type":"issue_complete",
     "version":1,
     "data":[
        {
           "groupId":"123456789012",
           "srrId":"123456789012",
           "srrCid":"bafkreid6i2u5b26hepprrkcswqoknzpyl2mrvuoy2ewuktj6ye5bxl3mby",
           "externalId": "your-id-as-string-123",
           "metadata":{
              "digest":"f84857e1b23ea78fb18a6393fdf617160c6771944a54772d6dbda37fb38d4d98",
              "createdAt":"2020-12-02T07:47:43.933Z",
              "updatedAt":"2020-12-14T05:48:23.000Z",
              "cid":"bafkreid6i2u5b26hepprrkcswqoknzpyl2mrvuoy2ewuktj6ye5bxl3mby",
              "json":{
                 "$schema":"https://api.startrail.io/api/v1/schema/registry-record-metadata.v1.1.schema.json",
                 "$schemaIntegrity":"sha256-fff288406b907ee6472585388bf519573628e45592be368f128b5b1e37a947c9",
                 "startbahnCertICTagUIDs":[
                    "1234567890abcdef"
                 ],
                 "title":{
                    "en":"A title",
                    "ja":"タイトル",
                    "zh":"一个标题"
                 },
                 "size":{
                    "width":200,
                    "height":400,
                    "depth":12.4,
                    "unit":"pixel",
                    "flexibleDescription":{
                       "en":"flexibleDescription comes here",
                       "ja":"自由だーーー"
                    }
                 },
                 "medium":{
                    "en":"Oil on canvas",
                    "ja":"キャンバスに油彩",
                    "zh":"布面油画"
                 },
                 "edition":{
                    "uniqueness":"unique work",
                    "proofType":"ED",
                    "number":1,
                    "totalNumber":3,
                    "note":{
                       "en":"some extra notes in 1 or more languages"
                    }
                 },
                 "contractTerms":{
                    "royaltyRate":15.7,
                    "fileURL":"https://startrail.io/whitepaper/startrail_wp_en_v1.1.pdf"
                 },
                 "note":{
                    "en":"note",
                    "zh":"注意"
                 },
                 "thumbnailURL":"https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
                 "yearOfCreation":{
                    "en":"around 2010-2020",
                    "ja":"2010年から2020年頃"
                 },
                 "isDigital":true,
                 "digitalDataHash":"sha256-247e4b904322a1dd0b148cd77e8627ec7d391251380880ab4621726ecb945ef5"
              }
           }
        }
     ]
  }

Webhook Event: Transfer reservation of SRR completed with Transfer Key

Subscription Name

transferReservationComplete

Trigger

After the start of an SRR Transfer using the Generate Transfer Key has been confirmed, the subscribed old owner will receive this notification.

Content

An array of data that can be used to trigger a transfer. Notably contains the SRR metadata, srrId and the encryptedTransferKey . The latter can be decrypted and then used to finalize the transfer to a target address of your choice. See “Public key” for how to get a public key.

• Parameter Details * indicates that the field will always exist from Startbahn side.

  Parameter	Webhook Type	Description	Format
  data[*].transferCid	transferReservationComplete	CID of the transfer metadata in IPFS. Refer to CID Documentation	string
  data[*].dataUrl*	transferReservationComplete	URL of the data used in SRR.	string
  data[*].encryptedTransferKey*	transferReservationComplete	Encrypted transfer key that can be used by the clients to determine the SRR on their system.	string
• Content Example

  {
     "type":"transfer_key",
     "version":1,
     "data":[
        {
           "groupId":"123456789012",
           "srrId":"123456789012",
           "transferCid":"bafkreid6i2u5b26hepprrkcswqoknzpyl2mrvuoy2ewuktj6ye5bxl3abc",
           "dataUrl":"https://url-to-your-artwork-file.com/path-to-file",
           "encryptedTransferKey":"s5/51w/2F5GeWpRf6Zfa0jRoHBO9yUQGxMYnkeU11jL5GCr6xKiAxmIrxij9iMK8S57GF/yrwKagF/zjz4ajgjUNATSJwdamlb4eTmJ+tdvGhlDiMpnWwJsgdYC56bQfaawOAnT1ydgoEOze0dxdSPPThiG9YHyzle8hpdKz2MbsEHMzU9ojjU9IAZSclIdenO1Nuq+pQockIJ4g+yqxQt8JD/xdHuBShNmlkwQhP4tcgjlSqnJDfmp5mfhbh+2bU/NFNb483TkWqN5x0k5+wXdONrRHBsH99YLW0SGZ4pParwAfnrwy2x8MESCk3rvCiJ+ksO1PamA8vbYPKszoQA==",
           "metadata":{
              "digest":"f84857e1b23ea78fb18a6393fdf617160c6771944a54772d6dbda37fb38d4d98",
              "createdAt":"2020-12-02T07:47:43.933Z",
              "updatedAt":"2020-12-14T05:48:23.000Z",
              "cid":"bafkreid6i2u5b26hepprrkcswqoknzpyl2mrvuoy2ewuktj6ye5bxl3mby",
              "json":{
                 "$schema":"https://api.startrail.io/api/v1/schema/registry-record-metadata.v1.1.schema.json",
                 "$schemaIntegrity":"sha256-fff288406b907ee6472585388bf519573628e45592be368f128b5b1e37a947c9",
                 "startbahnCertICTagUIDs":[
                    "1234567890abcdef"
                 ],
                 "title":{
                    "en":"A title",
                    "ja":"タイトル",
                    "zh":"一个标题"
                 },
                 "size":{
                    "width":200,
                    "height":400,
                    "depth":12.4,
                    "unit":"pixel",
                    "flexibleDescription":{
                       "en":"flexibleDescription comes here",
                       "ja":"自由だーーー"
                    }
                 },
                 "medium":{
                    "en":"Oil on canvas",
                    "ja":"キャンバスに油彩",
                    "zh":"布面油画"
                 },
                 "edition":{
                    "uniqueness":"unique work",
                    "proofType":"ED",
                    "number":1,
                    "totalNumber":3,
                    "note":{
                       "en":"some extra notes in 1 or more languages"
                    }
                 },
                 "contractTerms":{
                    "royaltyRate":15.7,
                    "fileURL":"https://startrail.io/whitepaper/startrail_wp_en_v1.1.pdf"
                 },
                 "note":{
                    "en":"note",
                    "zh":"注意"
                 },
                 "thumbnailURL":"https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
                 "yearOfCreation":{
                    "en":"around 2010-2020",
                    "ja":"2010年から2020年頃"
                 },
                 "isDigital":true,
                 "digitalDataHash":"sha256-247e4b904322a1dd0b148cd77e8627ec7d391251380880ab4621726ecb945ef5"
              }
           }
        }
     ]
  }

Webhook Event: Transfer execution of SRR completed

Subscription Name

transferExecutionComplete

Trigger

After an SRR has been transferred to a new user, the subscribed old owner receives this notification

Content

The array of data about a transfer on one of your SRRs to a new owner. Specifically contains the srrID , the new owner's Ethereum Address newOwnerEoa and the SRR metadata.

• Parameter Details * indicates that the field will always exist from Startbahn side.

  Parameter	Webhook Type	Description	Format
  data[*].transferCid	transferExecutionComplete	CID of the transfer metadata in IPFS. Refer to CID Documentation	string
  data[*].newOwnerEoa*	transferExecutionComplete	The EOA of the SRR’s new owner	string
• Content Example

  {
     "type":"transfer_complete",
     "version":1,
     "data":[
        {
           "groupId":"123456789012",
           "srrId":"123456789012",
           "transferCid":"bafkreid6i2u5b26hepprrkcswqoknzpyl2mrvuoy2ewuktj6ye5bxl3abc",
           "newOwnerEoa":"0x887C0d2340d2Fa144289C2E2BF835556f5c6C4E0",
           "metadata":{
              "digest":"f84857e1b23ea78fb18a6393fdf617160c6771944a54772d6dbda37fb38d4d98",
              "createdAt":"2020-12-02T07:47:43.933Z",
              "updatedAt":"2020-12-14T05:48:23.000Z",
              "cid":"bafkreid6i2u5b26hepprrkcswqoknzpyl2mrvuoy2ewuktj6ye5bxl3mby",
              "json":{
                 "$schema":"https://api.startrail.io/api/v1/schema/registry-record-metadata.v1.1.schema.json",
                 "$schemaIntegrity":"sha256-fff288406b907ee6472585388bf519573628e45592be368f128b5b1e37a947c9",
                 "startbahnCertICTagUIDs":[
                    "1234567890abcdef"
                 ],
                 "title":{
                    "en":"A title",
                    "ja":"タイトル",
                    "zh":"一个标题"
                 },
                 "size":{
                    "width":200,
                    "height":400,
                    "depth":12.4,
                    "unit":"pixel",
                    "flexibleDescription":{
                       "en":"flexibleDescription comes here",
                       "ja":"自由だーーー"
                    }
                 },
                 "medium":{
                    "en":"Oil on canvas",
                    "ja":"キャンバスに油彩",
                    "zh":"布面油画"
                 },
                 "edition":{
                    "uniqueness":"unique work",
                    "proofType":"ED",
                    "number":1,
                    "totalNumber":3,
                    "note":{
                       "en":"some extra notes in 1 or more languages"
                    }
                 },
                 "contractTerms":{
                    "royaltyRate":15.7,
                    "fileURL":"https://startrail.io/whitepaper/startrail_wp_en_v1.1.pdf"
                 },
                 "note":{
                    "en":"note",
                    "zh":"注意"
                 },
                 "thumbnailURL":"https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
                 "yearOfCreation":{
                    "en":"around 2010-2020",
                    "ja":"2010年から2020年頃"
                 },
                 "isDigital":true,
                 "digitalDataHash":"sha256-247e4b904322a1dd0b148cd77e8627ec7d391251380880ab4621726ecb945ef5"
              }
           }
        }
     ]
  }

Collection Related

Generic Collection Related Parameter

Additional to Generic Parameter Details above, these fields exist in webhook payload of all events related to the collection.

* indicates that the field will always exist from Startbahn side.

Parameter	Webhook Type	Description	Format
data[*].name*	collection	Name of the collection	string
data[*].symbol*	collection	Symbol of the collection	string

Webhook Event: Collection Created

Subscription Name

collectionCreated

Trigger

After a collection is created.

Content

Array of data about the creation of collection.

Parameter Details * indicates that the field will always exist from Startbahn side.

Parameter	Webhook Type	Description	Format
data[*].contractAddress	collectionCreated	Address of the collection	string
data[*].ownerAddress	collectionCreated	LUW Address of the owner	string

Content Example

{
   "type":"transfer_complete",
   "version":1,
   "data":[
      {
         "groupId": "0x9f25c0d8eB5f461528ab5E02f1F31C77885d5Dc0collection name",
         "contractAddress": "0x229dbFE303C5706BDB570A42f0BA190621d2D032",
         "ownerAddress": "0x9f25c0d8eB5f461528ab5E02f1F31C77885d5Dc0",
         "name": "collection name",
         "symbol": "TT"
      }
   ]
}

Webhook Event: Collection Create Failed

Subscription Name

collectionCreateFailed

Trigger

After a collection creation transaction failed to be mined.

Content

Array of data about failure of collection creation.

Parameter Details No additional value other than the Generic Collection Related Parameter.

Content Example

{
   "type":"transfer_complete",
   "version":1,
   "data":[
      {
         "groupId": "0x9f25c0d8eB5f461528ab5E02f1F31C77885d5Dc0collection name",
         "ownerAddress": "0x9f25c0d8eB5f461528ab5E02f1F31C77885d5Dc0",
         "name": "collection name",
         "symbol": "TT"
      }
   ]
}

Necessary data for Startbahn from our API users to integrate our webhooks into your services

To subscribe to webhooks, the API requires the following data * indicates required.

Parameter	Description	Format
Webhook URL*	The URL for API given by client where Startbahn needs to call to send the transfer key using webhook.	URL example: https://www.your-company.com/srr-integration-webhooks/
API Key*	Key used in Webhook for Authentication. Startbahn will put this key in the Webhook authentication header, so that your system can verify incoming API call that are made by Startbahn. this API key should be different from the one you use for Issue API.	Any string matching ^[a-zA-Z0-9_+-]{30,100}$ example: e46b1263-e3f5-461d-bfe7-18aff21c5ed3
Public Key	RSA Key used to encrypt the Transfer Key in the Webhook. The Client will hold the private key, so they can decrypt the Transfer Key. This is only needed when using the transfer key integration.	JSON object describing the key. example: {"alg":"RSA-OAEP-256","e":"AQAB","ext":true,"key_ops":["encrypt"],"kty":"RSA","n":"yNtyR6PTWi_7Fabm6YIpLALA5YHqiY7vrjU8mdPdO1sCawbelPoP0VUi52YUFqh-io25YCOdkWNNUagD-wirb1YNFPN4kpYNZUZaJtu__33cVO36hyoPlFDUGepiPMryKjcujhTcbJvtgQQncO6JQ35LzQZR4P4xF7E5Yy1vaim1dPiUpabHBq_ILgyHAirlbVCw7DhWo3TNs0rr3MsbxOnEec2ieIa1nEP3zN60kcn9Ky6Tehr-hUtjQpKB8EftW7zdO3JF8Lz6CTyWgodAj5owrLmA9rmCTXC5o7Fhm5I8R4H5JrBmYFi2saqqtxDUi9LQk6cbQjnyfbO3OqSkRw"} * You can generate a public/private key pair on this page (https://codesandbox.io/s/subtlecrypto-rsa-ttql3 ) or use another solution with the same encryption parameters.
Number of tries	Number of tries of the webhook that should be made , Integer i with 1 ≤ i ≤ 5 If no value is specified, we will use 1 as default value	Number / Integer Example Value 1 = One webhook call Value 2 = One webhook call + 1 Retry
Contact email Address	Email address where the email regarding failure of webhook should be sent. The email will contain the same information as webhook that failed, in a csv file (e.g. for a reservation webhook: SRR ID, Encrypted Transfer Key, dataUrl, Metadata)	Email Address [e-mail]
Webhook Events you want to subscribe to*	Your selected webhooks. You will only receive the events you want to. It is possible to change your subscriptions for future events if needed.	List of values Subscription Name.