Webhooks

Introduction

Webhooks are a widely accepted method of updating the state of a web application with custom callbacks. At Trinsic, we use webhooks to connect your Trinsic Agency with your own internal service.

There are currently 2 types of webhooks:

1. Notification webhooks - used to send alerts and notifications after an important event occurs
2. Endorser webhooks (Coming soon) - used to call another running agent to sign a request that will be submitted to the ledger. To use endorser signing webhooks, you must set up your Organization for delegated signing during registration.

Notification Webhooks

It is possible to use all of the software services we offer without configuring webhook notifications, but configuring them makes automatic responses much easier. For example, if an organization requests a verification from a user, the user can either accept or reject the verification. If an organization wants to issue a credential upon the verification being accepted, then the organization needs to know when the verification has been accepted. They can either listen for a webhook notification or poll the verification status to check for updates. Using a webhook configuration uses fewer resources and does not have downtime between poll cycles.

There are currently 4 events that will trigger a notification webhook: new connection, verification completion, new inbox message, and credential request.

Setup

It is very simple to set up a notification webhook endpoint.

1. Create a publicly available endpoint that accepts HTTP POST requests. The body of the request will be set to application/json and will contain one of the following JSON bodies, depending on which type of notification is sent.
2. Register this endpoint with your Trinsic Organization. Do so either in Trinsic Studio, or using our API.

Register in Studio

1. Select the organization for which you'd like to receive notifications
2. Select Webhooks from the sidebar
3. Click the + Webhook button
4. Enter the listening endpoint URL and click Add Webhook

New Connection

When a user accepts a connection invitation, a New Connection webhook is sent to registered webhook endpoints.

The webhook request body looks like the following:

{
  "message_type": "new_connection",
  "object_id": connection_id
}

Verification

When a user accepts a verification request and presents the required information, a Verification webhook is sent to registered webhook endpoints.

The webhook request body looks like the following:

{
  "message_type": "verification",
  "object_id": verification_id,
  "data": {
    "ConnectionId": connection_id
  }
}

New Inbox Message

When a user sends a message to the organization, a New Inbox Message webhook is sent to registered webhook endpoints.

The webhook request body looks like the following:

{
  "message_type": "new_inbox_message",
  "object_id": message_id,
  "data": {
    "ConnectionId": connection_id
  }
}

Credential Offer

When a credential has been offered, a Credential Offer webhook is sent to registered webhook endpoints.

The webhook request body looks like the following:

{
    "message_type": "credential_offer",
    "object_id": "credential_id",
    "data":
    {
        "ConnectionId": "connection_id",
        "WalletId": "wallet_id",
        "CorrelationId": "correlation_id"
    }
}

Credential Request

When a user accepts an offered credential, a Credential Request webhook is sent to registered webhook endpoints.

The webhook request body looks like the following:

{
  "message_type": "credential_request",
  "object_id": credential_id,
  "data": {
    "ConnectionId": connection_id
  }
}

When this notification is received, the next step is typically to issue the credential. This intermediary step (receiving a webhook and issuing the credential) can be skipped altogether by setting automaticIssuance to true when offering the credential.