Set up webhook verification

Thredd signs webhook payloads so that your application can verify that a webhook was sent by Thredd and has not been modified.

Before processing a webhook, your application should verify its signature using the public signing keys published by Thredd.
Thredd webhooks are sometimes also referred to as the Thredd Event Delivery System or EDS.

How webhook signature verification works

When Thredd sends an event to your webhook endpoint:

  1. Thredd signs the webhook payload.

  2. Your application receives the webhook and reads the signing key identifier (kid).

  3. Your application retrieves the available public signing keys from the Thredd JWKS endpoint.

  4. Your application selects the key that matches the kid.

  5. Your application verifies the signature.

  6. Your application processes the event only if verification succeeds.

Before you start

You need:

  • A webhook endpoint that is accessible to Thredd.

  • The JWKS URL for your Thredd environment.

  • Logic in your application to retrieve and cache JWKS signing keys.

  • Logic to verify incoming webhook signatures.

Retrieve your JWKS endpoint

Thredd's Public Key Infrastructure (PKI) provides a JSON Web Key Set (JWKS) endpoint that you can use to validate signatures.

An Organisation Admin must log in to the Thredd Portal and obtain the JWKS endpoint details.

To view your JWKS endpoint in Thredd Portal:

  1. Log in to Thredd Portal.

  2. Navigate to the System Admin menu, select Organisation, and then select EHI Configuration.

  3. The EHI Configuration page opens. Locate the JWKS endpoint and copy its URL.

The address of the JWKS endpoint should be similar to the following:

https://jwks.threddid.com/{thredd_org_id}

You must replace the placeholder {thredd_org_id} in the example JWKS endpoint URL with your unique organisation ID.

Use the JWKS URL for the environment that sends the webhook. If you use a JWKS URL from a different environment, signature verification will fail.

Retrieve the signing keys

Retrieve the JSON Web Key Set (JWKS) from the Thredd JWKS endpoint.

Your application should cache the retrieved keys rather than requesting the JWKS for every webhook.

Your implementation should also be able to refresh the cache when Thredd rotates its signing keys. AWS-based webhook verification requires clients to support key discovery and key rotation.

Select the signing key

When you receive a webhook:

  1. Read the kid from the webhook signature information.

  2. Find the corresponding key in the JWKS.

  3. If the key is not available in your cache, refresh the JWKS.

  4. Select the public key whose kid matches the webhook.

Do not attempt to verify the payload using an unrelated signing key.

Verify the signature

Verify the webhook signature before processing the event.

Your application should reject a webhook if:

  • The signature is missing.

  • Signature verification fails.

  • The payload has been modified.

  • The signature is no longer valid.

Only process the event after verification succeeds.

Register your webhooks

When creating the webhook registration via the API, set certificateAuthority to AWS. This configures Thredd to sign webhook payloads using the AWS signing keys exposed through the Thredd JWKS endpoint.

You can create a webhook by making a POST request to the Create Webhook endpoint. For example:

POST https://api.thredd.com/eds/api/v1/Webhooks

Example Create Webhook request:

Copy 
{
"productId": 12345,
"events": [101],
"webhookStatus": "active",  
"config": {
    "url": "https://client_domain.com/webhook",
    "certificateAuthority": "AWS",
    "customHeaders": {
        "header1": "value_1",
        "header2": "value_2"
        }
    }
}

If successful, a 201 response is returned with the details of the newly registered webhook.

For more information, see:

Test your integration

Before moving to production, verify that your webhook receiver:

  • Receives events successfully.

  • Accepts correctly signed payloads.

  • Rejects incorrectly signed payloads.

  • Rejects modified payloads.

  • Selects the correct signing key using kid.

  • Refreshes cached signing keys when required.

Implementation checklist

  • Create an endpoint to receive Thredd webhooks.

  • Obtain the JWKS URL for your environment.

  • Retrieve and cache the JWKS signing keys.

  • Read the kid from incoming webhook signature information.

  • Select the matching public key.

  • Verify every webhook signature before processing the payload.

  • Handle JWKS key rotation.

  • Set certificateAuthority to AWS when registering the webhook.

  • Test successful and failed signature verification.

  • Validate the complete webhook flow in a non-production environment before going live.