Webhook Setup

Overview

Startbahn delivers integration events from your Licensed User Wallet (LUW) to an HTTPS endpoint you control. Each event is sent as a JSON POST request and is retried on failure.

You can use webhooks to react to on-chain activity in near real-time — for example, persisting newly issued SRRs, advancing a transfer flow once the on-chain reservation is confirmed, or updating internal state when a collection contract finishes deploying.

Webhook subscriptions are not self-service today. The Startbahn team will configure your endpoint, API key, and the set of events you want to receive based on the Subscribing to webhooks information you provide.

Events at a glance

Subscription name	Payload type	Fires when
issueComplete	issue_complete	One or more SRRs have been minted.
transferReservationComplete	transfer_key	A transfer has been reserved on-chain (transfer key flow).
transferExecutionComplete	transfer_complete	A transfer has executed on-chain and the owner changed.
collectionCreated	collection_created	A collection contract has been deployed.
collectionCreateFailed	collection_create_failed	A collection-creation transaction failed to be mined.

Delivery model

Request format

Each delivery is an HTTP POST to your configured URL with a JSON body and the following headers:

Content-Type: application/json
x-api-key: <the API key you provided when subscribing>

Use the x-api-key header to authenticate the request on your side. Treat the key as a shared secret.

Expected response

Respond with any 2xx status to acknowledge receipt. Your endpoint should respond quickly; long-running work should be queued on your side and processed asynchronously.

Retries and cancellation

If your endpoint returns a non-2xx status, times out, or is unreachable, the delivery is retried. You can configure the total number of attempts (between 1 and 5, default 1).

Once every attempt fails, Startbahn:

1. Marks the delivery as cancelled and stops retrying it.

2. Sends an informational email (in CSV format) to the contact email you provided, containing the same data that the webhook would have delivered.

Cancellations are per-delivery — subsequent events are still attempted independently.

Batching and groupId

When multiple events of the same type are destined for the same URL and API key, they may be combined into a single delivery whose data array contains all of them.

Each entry in data carries a groupId so you can correlate or deduplicate entries:

• For SRR-related events, groupId is the SRR's token ID.

• For collection-related events, groupId is ${ownerAddress}${name} — i.e. the LUW address concatenated with the collection name.

Common payload structure

Every webhook body shares the same envelope:

{
  "type": "<event payload type>",
  "version": <integer>,
  "data": [ /* one or more entries */ ]
}

* indicates the field is always present.

Field	Format	Description
type*	enum	One of issue_complete, transfer_key, transfer_complete, collection_created, collection_create_failed.
version*	integer	Payload schema version. SRR events are currently 2; collection events are currently 1.
data*	array	One or more entries. The shape of each entry depends on type.
data[*].groupId*	string	Identifier used to group related entries inside a single delivery. See Batching and groupId.

Forward compatibility: We may add new fields to a payload without bumping version. Make sure your parser ignores unknown fields rather than rejecting them. Removals will be announced and deprecated first.

SRR webhook events

The three SRR events (issueComplete, transferReservationComplete, transferExecutionComplete) share a common set of fields in addition to the envelope above.

Fields common to all SRR events

Field	Format	Description
data[*].srrId*	string	The SRR's token ID.
data[*].collectionContractAddress*	string | null	Address of the collection contract the SRR lives on. null means the SRR is on the default collection. Added in payload version: 2.
data[*].metadata	object	Raw SRR metadata JSON. See Metadata Schema for the shape.

srrId is not globally unique — two SRRs on two different collections can share the same token ID. Treat (collectionContractAddress, srrId) as the unique identifier when persisting or looking up SRRs on your side.

data[*].metadata shape

data[*].metadata is the raw SRR metadata JSON — the same object you can fetch from the Startrail IPFS CDN gateway at https://cdn.startrail.io/ipfs/<cid>. It is not wrapped in a { digest, json, createdAt, updatedAt, cid } envelope.

The CID is conveyed separately:

• On issueComplete, via data[*].srrCid (when available).

• On transferReservationComplete / transferExecutionComplete, the CID is not on the payload — look the SRR up on the subgraph by srrId to get the current metadataDigest.

issueComplete

Fires after one or more SRRs have been minted by the subscribed issuer.

Event-specific fields

Field	Format	Description
data[*].srrCid	string	CID of the SRR metadata on IPFS. Provided when the issuance flow knows the CID. See CID documentation.

Example payload

{
  "type": "issue_complete",
  "version": 2,
  "data": [
    {
      "groupId": "123456789012",
      "srrId": "123456789012",
      "collectionContractAddress": null,
      "srrCid": "bafkreid6i2u5b26hepprrkcswqoknzpyl2mrvuoy2ewuktj6ye5bxl3mby",
      "metadata": {
        "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.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://cdn.startrail.io/ipfs/bafkreigb2wjgin53xgmaiqxvdn4g2iw6cnmp4e3w3nzopmom53sjborque",
        "yearOfCreation": {
          "en": "around 2010-2020",
          "ja": "2010年から2020年頃"
        },
        "isDigital": true,
        "digitalDataHash": "sha256-247e4b904322a1dd0b148cd77e8627ec7d391251380880ab4621726ecb945ef5"
      }
    }
  ]
}

transferReservationComplete

Fires after a transfer reservation has been confirmed on-chain (the transfer-key flow). The subscribed previous owner receives the notification.

Event-specific fields

No fields beyond the common SRR fields.

The legacy transferCid, dataUrl, and encryptedTransferKey fields are no longer emitted on this webhook. If you need the encrypted transfer key, fetch it through the separate transfer-key API.

Example payload

{
  "type": "transfer_key",
  "version": 2,
  "data": [
    {
      "groupId": "123456789012",
      "srrId": "123456789012",
      "collectionContractAddress": null,
      "metadata": {
        "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.1.schema.json",
        "title": { "en": "A title" }
        // ... full SRR metadata JSON, same shape as on the IPFS CDN gateway
      }
    }
  ]
}

transferExecutionComplete

Fires after a transfer has executed on-chain and the SRR's owner has changed. The subscribed previous owner receives the notification.

Event-specific fields

Field	Format	Description
data[*].newOwnerEoa*	string	EOA address of the SRR's new owner.

The legacy transferCid field is no longer emitted on this webhook. If you need the transfer's provenance entry, query it from the subgraph by srrId.

Example payload

{
  "type": "transfer_complete",
  "version": 2,
  "data": [
    {
      "groupId": "123456789012",
      "srrId": "123456789012",
      "collectionContractAddress": null,
      "newOwnerEoa": "0x887C0d2340d2Fa144289C2E2BF835556f5c6C4E0",
      "metadata": {
        "$schema": "https://api.startrail.io/api/v1/schema/registry-record-metadata.v2.1.schema.json",
        "title": { "en": "A title" }
        // ... full SRR metadata JSON, same shape as on the IPFS CDN gateway
      }
    }
  ]
}

Collection webhook events

Collection events relate to the lifecycle of a collection contract owned by your LUW. The two events share a common set of fields in addition to the envelope.

Fields common to all collection events

Field	Format	Description
data[*].name*	string	Name of the collection.
data[*].symbol*	string	Symbol of the collection.

For collection events, groupId is composed as ${ownerAddress}${name} and matches across the success and failure events for the same attempt.

collectionCreated

Fires after a collection contract has been deployed.

Event-specific fields

Field	Format	Description
data[*].contractAddress*	string	Address of the newly deployed collection contract.
data[*].ownerAddress*	string	LUW address that owns the collection.

Example payload

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

collectionCreateFailed

Fires when a collection-creation transaction fails to be mined.

Event-specific fields

No fields beyond the common collection fields. The owner address can be recovered from the groupId (which encodes ${ownerAddress}${name}) or correlated with the originating request on your side.

Example payload

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

Subscribing to webhooks

To enable webhook delivery, provide Startbahn with the following information.

* indicates the field is required.

Field	Description	Format / Example
Webhook URL*	The HTTPS endpoint where Startbahn will POST events.	https://www.your-company.com/srr-integration-webhooks/
API Key*	Shared secret that Startbahn will send in the x-api-key header. Use this on your side to authenticate the request. This key should be different from your Issue API key.	Any string matching ^[a-zA-Z0-9_+-]{30,100}$ Example: e46b1263-e3f5-461d-bfe7-18aff21c5ed3
Public key	RSA public key used to encrypt the transfer key when using the transfer-key integration. You hold the private key and use it to decrypt. Only required when subscribing to transferReservationComplete with the transfer-key flow.	JSON object describing the key. Example: {"alg":"RSA-OAEP-256","e":"AQAB","ext":true,"key_ops":["encrypt"],"kty":"RSA","n":"...","..."} You can generate a key pair at this SubtleCrypto example or with any tool using equivalent parameters.
Number of tries	Total delivery attempts before the event is cancelled, integer 1 ≤ n ≤ 5. Defaults to 1 if omitted.	Integer. 1 = single attempt, no retries. 2 = single attempt + 1 retry.
Contact email	Email address that receives a CSV with the event data when all delivery attempts have failed.	[e-mail]
Webhook events to subscribe to*	The subscription names you want to receive. You can change the subscription set at any time for future events.	List of subscription names from the events table.