Subscriptions

Like a blockchain, Asset Register is event driven and therefore subscribers must be given real time feedback on what is happening so they can react to them.

Event

When you subscribe to an event you will receive the full transaction that includes the event you are interested in.

{
  "status": "SUCCESS",
  "signature": "0x00",
  "message": "",
  "events": [
    {
      "type": "asset-link",
      "action": "delete",
      "args": [
        "equipWith_asmBrain",
        "did:fv-asset:1:evm:0x6bca6de2dbdc4e0d41f7273011785ea16ba47182:1000",
        "did:fv-asset:1:evm:0x1ea66a857de297471bc12dd12d93853ff6617284:200",
      ],
      "collectionId": "1:evm:0x6bca6de2dbdc4e0d41f7273011785ea16ba47182"
    }
  ]
}

Webhook

Like any other webhook subscription, the Asset Register Subscription Service will forward the events via a POST request with the API_KEY set in the headers, ensuring the origination of the request.

If an event delivery to a webhook endpoint is attempted and an error occurs, the following takes place:

• Events associated with error codes 409, 429, and 5xx are retried.

• Events associated with error codes 1xx, 2xx, 3xx, and 4xx (excluding 429) are not retried.

We read the standard HTTP response header Retry-After to determine how long to wait before making a follow-up request. We then choose the more conservative value between the defined retry policy and the Retry-After header. If Retry-After value is negative, the event will not be retried.

Usage

You must send a valid SIWE token for the following interactions. Please see Admin Authentication.

The following mutations demonstrate the main use cases. However, additional mutations for managing endpoints are available. To explore the complete set of mutations, refer to the GraphQL playground by navigating to the GraphQL URL in your browser.

Creating a webhook endpoint

Before you can create a subscription, a webhook endpoint must be created. This will point all the subscriptions to the correct URL and will set you up with an API Key for request authentication.

mutation CreateWebhookEndpoint($input: CreateWebhookEndpointInput!) {
  createWebhookEndpoint(input: $input) {
    webhookEndpoint {
      id
      webhookId
      subscriber
      url
      apiKey
      retries
      createdAt
    }
  }
}

{
  "input": {
    "url": "https://example.com/webhook",
    "retries": 5
  }
}

The retries property determines the number of times the webhook endpoint will be retried before stopping. The maximum allowable number of retries is set at 20.

The webhookId from the response should be used whenCreating a subscription.

Creating a subscription

mutation CreateWebhookSubscription($input: CreateWebhookSubscriptionInput!) {
  createWebhookSubscription(input: $input) {
    webhookSubscription {
      id
      subscriptionId
      webhookId
      type
      actions
      collectionId
      createdAt
    }
  }
}

{
  "input": {
    "type": "asset-link",
    "actions": ["create", "delete"],
    "collectionId": "1:evm:0x6bca6de2dbdc4e0d41f7273011785ea16ba47182",
    "webhookId": "8fafd82a-ca5e-4495-9ad4-d28c4ea6adf0"
  }
}

Querying subscription resources

You can use the following queries to get subscription resources created by the requester:

• webhookEndpoint

• webhookEndpoints

• webhookSubscription

• webhookSubscriptions