Skip to content



Webhooks enable providers to receive updates whenever an event occurs within the ecosystem they manage.

Configuring Webhooks

Webhooks may be added to an ecosystem using the AddWebhook method; either with the CLI or any of our SDKs. In the future, webhooks will also be configurable through a web dashboard.

The value chosen for secret should be a UTF-8 string which is never published anywhere; it is used to verify incoming payloads.

The destination_url of a webhook must be an HTTPS URL accessible over the internet.

Event Type Filtering

By default, webhooks receive all event types, but can be configured to only trigger on a specific subset of events.

Receiving Webhooks

Webhooks are sent as JSON strings to your specified URL (which must be HTTPS) using the POST method.


The structure of a webhook payload is shown below. Event-specific information is stored in data; its format is event-specific.

Field Type Description
id string The ID of the event which triggered the webhook
timestamp timestamp The timestamp of the event
type string The type of event contained in data
data object The data of the event itself


Because webhooks are URLs accessible over the internet, it is necessary to ensure that a webhook comes from Trinsic and not an attacker.

Trinsic hashes payloads using HMAC-SHA256, using the secret you provided during webhook creation as the secret key, and the raw POST body as the message contents.

This hash is sent with the request as a header named trinsic-signature-sha256.

Your verification code may look like the following pseudocode:

message = http_request.post_body
trinsic_hash = http_request.headers["trinsic-signature-sha256"]

computed_hash = hmac_sha256(message, stored_secret)

if(trinsic_hash != computed_hash) {
    // Hash failed verification. This is not a genuine webhook from Trinsic.

Use a library

It is highly recommended that you use a library to compute and verify HMACs.

Many languages have native support for HMAC-SHA256; for those that don't, high-quality open source libraries exist.

Enabling Wallet Events

Events which occur on a wallet will not be sent to your webhooks unless the wallet holder has opted in.

To receive webhooks for wallet events, the AuthorizeWebhook method must be called for each wallet which is opting-in to propagate wallet events to the ecosystem provider.

This call must be performed using the wallet's authentication token.

Event Types

For a list of all event types and their structures, see the Events Reference page.