# 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

{% hint style="info" %}
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.
{% endhint %}

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

### **Generic Parameter Details**

<mark style="color:red;">`*`</mark> indicates that the field will always exist from Startbahn side.

<table><thead><tr><th width="283">Parameter</th><th width="148">Webhook Type</th><th width="237">Description</th><th width="234">Format</th><th></th></tr></thead><tbody><tr><td>type<mark style="color:red;">*</mark></td><td>All</td><td>The type of the webhook</td><td>ENUM consists of <code>transfer_key</code> , <code>transfer_complete</code>, <code>issue_complete</code></td><td></td></tr><tr><td>version<mark style="color:red;">*</mark></td><td>All</td><td>The version of the webhook.</td><td>number</td><td></td></tr><tr><td>data<mark style="color:red;">*</mark></td><td>All</td><td>The data related to the webhook that client’s need to process.</td><td>Array</td><td></td></tr><tr><td>data[*].groupId<mark style="color:red;">*</mark></td><td>All</td><td>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.</td><td>string</td><td></td></tr></tbody></table>

## SRR Related

### Generic SRR Related Parameter

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

<table><thead><tr><th width="283">Parameter</th><th width="148">Webhook Type</th><th width="237">Description</th><th width="234">Format</th></tr></thead><tbody><tr><td>data[*].srrId<mark style="color:red;">*</mark></td><td>All</td><td>SRR Token ID</td><td>string</td></tr><tr><td>data[*].metadata<mark style="color:red;">*</mark></td><td>All</td><td>Metadata of the SRR</td><td>Object</td></tr><tr><td>data[*].metadata.digest<mark style="color:red;">*</mark></td><td>All</td><td>Digest of the metadata</td><td>string</td></tr><tr><td>data[*].metadata.json<mark style="color:red;">*</mark></td><td>All</td><td>JSON of the metadata. <a href="../../metadata-schema/startrail-registry-srr">Details</a></td><td>Object</td></tr><tr><td>data[*].metadata.cid</td><td>All</td><td>CID of the SRR metadata in IPFS. Refer to <a href="https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid">CID Documentation</a></td><td>string</td></tr><tr><td>data[*].metadata.createdAt<mark style="color:red;">*</mark></td><td>All</td><td>Date of the metadata creation</td><td>Datetime</td></tr><tr><td>data[*].metadata.updatedAt<mark style="color:red;">*</mark></td><td>All</td><td>Date of the metadata update if any.</td><td>Datetime</td></tr></tbody></table>

### 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 `srrCid`.<br>

* | Parameter        | Webhook Type  | Description                                                                                                                      | Format |
  | ---------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------ |
  | data\[\*].srrCid | issueComplete | CID of the SRR metadata in IPFS. Refer to [CID Documentation](https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid) | string |
* Content Example

  ```json
  {
     "type":"issue_complete",
     "version":1,
     "data":[
        {
           "groupId":"123456789012",
           "srrId":"123456789012",
           "srrCid":"bafkreid6i2u5b26hepprrkcswqoknzpyl2mrvuoy2ewuktj6ye5bxl3mby",
           "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](#necessary-data-for-startbahn-from-our-api-users-to-integrate-our-webhooks-into-your-services)” for how to get a public key.

* **Parameter Details**\ <mark style="color:red;">`*`</mark> indicates that the field will always exist from Startbahn side.<br>

  | Parameter                                                        | Webhook Type                | Description                                                                                                                           | Format |
  | ---------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------ |
  | data\[\*].transferCid                                            | transferReservationComplete | CID of the transfer metadata in IPFS. Refer to [CID Documentation](https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid) | string |
  | data\[\*].dataUrl<mark style="color:red;">\*</mark>              | transferReservationComplete | URL of the data used in SRR.                                                                                                          | string |
  | data\[\*].encryptedTransferKey<mark style="color:red;">\*</mark> | transferReservationComplete | Encrypted transfer key that can be used by the clients to determine the SRR on their system.                                          | string |
* **Content Example**

  ```json
  {
     "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**\ <mark style="color:red;">`*`</mark> indicates that the field will always exist from Startbahn side.<br>

  <table><thead><tr><th width="236">Parameter</th><th width="248">Webhook Type</th><th width="237">Description</th><th>Format</th></tr></thead><tbody><tr><td>data[*].transferCid</td><td>transferExecutionComplete</td><td>CID of the transfer metadata in IPFS. Refer to <a href="https://docs.ipfs.tech/concepts/content-addressing/#what-is-a-cid">CID Documentation</a></td><td>string</td></tr><tr><td>data[*].newOwnerEoa<mark style="color:red;">*</mark></td><td>transferExecutionComplete</td><td>The EOA of the SRR’s new owner</td><td>string</td></tr></tbody></table>
* **Content Example**

  ```json
  {
     "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.

<mark style="color:red;">`*`</mark> indicates that the field will always exist from Startbahn side.

| Parameter                                          | Webhook Type | Description              | Format |
| -------------------------------------------------- | ------------ | ------------------------ | ------ |
| data\[\*].name<mark style="color:red;">\*</mark>   | collection   | Name of the collection   | string |
| data\[\*].symbol<mark style="color:red;">\*</mark> | 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**\ <mark style="color:red;">`*`</mark> indicates that the field will always exist from Startbahn side.

<table><thead><tr><th width="236">Parameter</th><th width="248">Webhook Type</th><th width="237">Description</th><th>Format</th></tr></thead><tbody><tr><td>data[*].contractAddress</td><td>collectionCreated</td><td>Address of the collection</td><td>string</td></tr><tr><td>data[*].ownerAddress</td><td>collectionCreated</td><td>LUW Address of the owner</td><td>string</td></tr></tbody></table>

**Content Example**

```json
{
   "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**

```json
{
   "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\ <mark style="color:red;">`*`</mark> indicates required.

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