API Reference

Webhooks

The Tetra Trust API has the ability to send webhook notifications.

Subscribing

To receive webhook notifications, you must subscribe a destination endpoint via Post webhook url. This endpoint must be configured as a POST endpoint.

Before receiving notifications, all endpoints must be confirmed by you. To confirm the endpoint, we will send a JSON payload such as this one:

{
    "Type": "SubscriptionConfirmation",
    "MessageId": "4f4da52d-7c96-427e-a86c-317f22a1f4fa",
    "Token": "2336412f37fb687f5d51e6e2425ba1f25480c5eb9360f7199f9e12f48dc22f3c060ff27a94e91423ff9685861980bd5423f59490bf67f7f9a9c5a0a46e69b7681715d1ee8d26c574ea63f52ed181151d4eef9e19683c63aa24df01c8a06e7478d270eb11b23a0feb1f5cc5e36d83c04e9c62eb4dda805eb959e330b0a43804c2",
    "TopicArn": "arn:aws:sns:ca-central-1:924644199836:mets-production-api-webhook",
    "Message": "You have chosen to subscribe to the topic arn:aws:sns:ca-central-1:924644199836:mets-staging-api-webhook.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
    "SubscribeURL": "https://sns.ca-central-1.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:ca-central-1:924644199836:mets-staging-api-webhook&Token=2336412f37fb687f5d51e6e2425ba1f25480c5eb9360f7199f9e12f48dc22f3c060ff27a94e91423ff9685861980bd5423f59490bf67f7f9a9c5a0a46e69b7681715d1ee8d26c574ea63f52ed181151d4eef9e19683c63aa24df01c8a06e7478d270eb11b23a0feb1f5cc5e36d83c04e9c62eb4dda805eb959e330b0a43804c2",
    "Timestamp": "2024-05-01T19:21:20.209Z",
    "SignatureVersion": "1",
    "Signature": "RjBvXpHq8C3gFDDsAQOhLfmBpvfRW/uzaYXiarifcoATEcHevI3dxx1aV2mEKscNzqlMCWAphSavObLxwNFh7ZEOpCtlbPXkr5nbro2gWFICyW4sGH3dpznybvI43HIVdkobEdoT1LbwiGc6rVvesqnUAeJ91cZGwxRinqicfrdKFvVljxLeerel1TutQaF2HUbLoLQF0Svy3c1ztlwci95WwfVPTAzfRLXw7Tw4UW3PnEvnOpCS/52lMaHfbWKbFYiyH6SRxIlFsuoFnRdl/+jsyt/BZuIa5aq0Kd51F3IJpNBM6kySZq6Q+TZj6j4+7YKZRpfTJ5R6rp0l1zTVFw==",
    "SigningCertURL": "https://sns.ca-central-1.amazonaws.com/SimpleNotificationService-60eadc530605d63b8e62a523676ef735.pem"
}

When you visit the SubscribeURL, the response will contain an XML document containing an element SubscriptionArn. This means that you endpoint is confirmed and notifications are enabled. You can double check your confirmed endpoints by hitting List webhook urls for your organization.

Note that the SubscribeURL in the confirmation JSON is only valid for 48 hours. After 48 hours, if it remains unconfirmed, it will be automatically unsubscribed.

Verifying Messages

To verify authenticity of messages, it is recommended to follow SNS Verifying Messages .

Retry Policy

A message is successfuly delivered if and only if the endpoint receiving the message returns status 200 OK. In the event that a notifications fails to deliver, we will attempt to re-deliver the notification a total of 8 times over the course of an hour, on an exponential backoff curve. The starting delay is set at 60 seconds.

🚧

Removal of Webhook Subscriptions

The Tetra Trust API will automatically unsubscribe your endpoint in one of two cases:

  1. Over the course of a week, 48 notifications fail to fully deliver
  2. Over the lifetime of the webhook, 240 notifications fail to fully deliver

Notifications

Webhook notifications are currently only supported for staking initiation. We will give access to the scope when staking initiation is requested and approved.

When hitting Create staking initiation request we will return an object containing a UUID in the field webhookId. You may use this to associate webhook notifications with your API initiated stakes.