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
SRR Related
Generic SRR Related Parameter
Additional from Generic Parameter Details, these fields exist in webhook payload of all events related to SRR.
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.
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.
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.
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.
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.