Skip to main content

Verifying a webhook

To allow Sovrin users to validate the integrity and authorship of webhooks generated by the Sovrin platform, all webhook events are signed using HTTP Message Signatures (an IETF draft standard).

tip

MATTR strongly encourages Sovrin users to verify each webhook event to provide a suitable level of protection to integrations consuming the event information. One way of doing this is to verify the HTTP signatures.

Sovrin users should also compare the webhookId that is generated at the creation of the webhook to the webhookId specified in the request.

Using HTTP-Signature Library​

Sovrin users can obtain the public keys from this endpoint.

tip

Users can obtain the public keys Sovrin uses to sign the HTTP request from this endpoint, these can be used to verify the HTTP signature. The response key set is relatively static and only expected to change on rare occasions, such as performing key rotation. Users should use the kid specified in the JWK key object to identify which key a particular HTTP request is signed with, as the key set can change or contain multiple keys.

Request​


GET https://api.sovrin.one/v1/webhooks/jwks

Response​


{
    "keys": [
        {
            "kty": "OKP",
            "crv": "Ed25519",
            "kid": "1608085995",
            "x": "1NYsB58B9bNmReXqyQR8R_DeJtoLHSW-JsyZVmV2EWQ"
        }
    ]
}

In order to facilitate customers verifying webhook requests from the Sovrin platform, we provide a typescript based library that can be used for verification purposes or serve as a reference implementation to develop a verification SDK in another programming language.

Access our NPM library here.

An open-source example of using the @mattrglobal/http-signatures library is also available.

Access the Sample App here.

To learn more about verifying our webhook requests, have a look at the Open Source MATTR Http-Signatures library here.