Verify a Webhook

To validate the integrity and authorship of Webhooks generated by the MATTR VII platform, all Webhook events are signed using HTTP Message Signatures (an IETF draft standard).

MATTR strongly encourages verifying 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.

You should also compare the webhookId that is generated at the creation of the Webhook to the webhookId specified in the request.

You can obtain the public keys MATTR VII uses to sign the HTTP and use them to verify the HTTP signature. The response key set is relatively static and only expected to change on rare occasions, such as when performing key rotation.

Request

Make the following request to retrieve the public keys:

1GET https://YOUR_TENANT_URL/v1/webhooks/jwks

Note that this endpoint is protected, and you will need to complete authentication to gain access. You can also cache the response as these public keys are not expected to change often.

Response

1{
2    "keys": [
3        {
4            "kty": "OKP",
5            "crv": "Ed25519",
6            "kid": "1608085995",
7            "x": "1NYsB58B9bNmReXqyQR8R_DeJtoLHSW-JsyZVmV2EWQ"
8        }
9    ]
10}

You 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.

Verification implementations

To facilitate verification of MATTR VII Webhook requests, we provide a typescript based library that can be used for verification 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.