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.

ParameterWebhook TypeDescriptionFormat

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.

ParameterWebhook TypeDescriptionFormat

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.

    ParameterWebhook TypeDescriptionFormat

    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.

    ParameterWebhook TypeDescriptionFormat

    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.

    ParameterWebhook TypeDescriptionFormat

    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.

ParameterWebhook TypeDescriptionFormat

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.

ParameterWebhook TypeDescriptionFormat

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.

ParameterDescriptionFormat

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 admin@webhook-client.com

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.

PreviousIssue & TransferNextCollection

Last updated

©2023 Startbahn, Inc.