From 1b8e3f16e496ed9860491c9e220363796e4141a7 Mon Sep 17 00:00:00 2001 From: James Gunn Date: Thu, 21 Nov 2024 11:27:40 +0000 Subject: [PATCH] Update webhooks doc to include jwks endpoint (#1694) --- README.md | 10 +++++----- docs/api-designs/webhooks.md | 13 ++++++++++--- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 7ab4e1376..a54f41e2d 100644 --- a/README.md +++ b/README.md @@ -52,12 +52,12 @@ See the [changelog](CHANGELOG.md) for the details of what has changed between ve ## Environments -| Name | URL | -| -------------- | ----------------------------------------------------------- | -| Production | https://teacher-qualifications-api.education.gov.uk | +| Name | API URL | +| --- | --- | +| Production | https://teacher-qualifications-api.education.gov.uk | | Pre-production | https://preprod.teacher-qualifications-api.education.gov.uk | -| Test | https://test.teacher-qualifications-api.education.gov.uk/ | -| Development | https://dev.teacher-qualifications-api.education.gov.uk/ | +| Test | https://test.teacher-qualifications-api.education.gov.uk/ | +| Development | https://dev.teacher-qualifications-api.education.gov.uk/ | ## Developer setup diff --git a/docs/api-designs/webhooks.md b/docs/api-designs/webhooks.md index e5b35bb04..ac826bbe0 100644 --- a/docs/api-designs/webhooks.md +++ b/docs/api-designs/webhooks.md @@ -66,10 +66,17 @@ If after the final retry the message was still not delivered successfully no fur ## Verifying the webhook -Follow [the spec](https://www.rfc-editor.org/rfc/rfc9421.html#name-verifying-a-signature) for verifying the webhook's signature. -You will be given a public key to use for verifying webhooks when your endpoint is configured. +See [the spec](https://www.rfc-editor.org/rfc/rfc9421.html#name-verifying-a-signature) for the details of how to verify the webhook's signature. -The `ping` message can be used to aid verification. +Signatures are made up of `content-digest`, `content-length`, `ce-id`, `ce-type`, and `ce-time` HTTP header components and the `target-uri` derived component. + +Each environment publishes the certificates to use for verification at `/webhook-jwks` (see [README.md](../../README.md#Environments) for the environment-specific base URL). +Each HTTP message signature contains the ID of the key that was used to sign the request. +Find the corresponding keys in the `/webhook-jwks` (identified by the `kid` parameter) and use this to verify the signature. + +Note that certificates are rotated from time-to-time so these should not be hard-coded anywhere or cached for too long. + +The `ping` message can be used during development to help with testing verification. ## Message types