Migrating your webhook integration

Thredd is moving webhook payload signing to an AWS-based signing service.

If you already receive Thredd webhooks, sometimes referred to as the Thredd Event Delivery System or EDS, update your webhook receiver to verify AWS-signed payloads before changing your webhook configuration. When your receiver is ready, update the webhook registration to set CertificateAuthority to AWS and verify incoming payload signatures using the Thredd Portal JWKS URL.

Your API integration through API Hub does not change as part of this Webhook migration. However, you will need to update your REST API authentication configuration separately as part of the wider migration effort.

Prerequisites

Before migrating:

  • Identify all webhook registrations that you need to migrate.

  • Know which Thredd environments each webhook uses.

  • Have the JWKS URL for each environment.

  • Can update and test your webhook signature verification logic.

Do not change your webhook to use AWS signing until your webhook receiver can successfully verify AWS-signed payloads. Otherwise, your system might reject valid webhook deliveries.

How AWS webhook signing works

When AWS signing is enabled, Thredd signs each webhook payload using an AWS-managed signing key.

Your webhook receiver:

  1. Receives the signed webhook.

  2. Reads the key identifier (kid) from the signature information.

  3. Retrieves the available public keys from the Thredd JWKS endpoint.

  4. Selects the public key that matches the kid.

  5. Verifies the webhook signature.

  6. Processes the webhook only if signature verification succeeds.

Your implementation should also support key caching and key rotation.

Migrate your webhooks

Identify your webhook registrations

Identify all existing Thredd webhook registrations and the environments in which they are used.

Migrate and test each environment separately.

Update your signature verification

Update your webhook receiver so that it can:

  • Retrieve public signing keys from the appropriate Thredd JWKS endpoint.

  • Identify the required public key using the kid supplied with the webhook.

  • Verify the webhook payload signature before processing the event.

  • Refresh the JWKS data when the required key is not available in your cache.

  • Handle verification failures without processing unverified webhook data.

Reject webhook payloads that are unsigned, incorrectly signed, expired, or have been modified.

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.Retrieve your JWKS endpoint URL

  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.

Test AWS signing

Test the integration in a non-production environment before migrating production.

Confirm that your webhook receiver:

  • Accepts correctly signed webhook payloads.

  • Rejects payloads with an invalid signature.

  • Rejects payloads that have been modified.

  • Can retrieve and cache the signing keys.

  • Can select the correct key using the kid.

Enable AWS signing

After your webhook receiver has been updated and tested, update the webhook registration and set:

Copy 
{
    "config": {
        "url": "string",
        "customHeaders": null,
        "certificateAuthority": "AWS"
        }    
}

Setting certificateAuthority to AWS tells Thredd to use AWS signing for webhook payloads.

Update webhook registration using the Update Webhook Details endpoint

You can update a webhook's registration details by making a PUT request to the Update Webhook Details endpoint, including the webhookId in the URL. For example:

PUT https://api.thredd.com/eds/api/v1/Webhooks/{webhookId}

When updating the webhook, you must include all fields in the request body even if they're not being updated. The full webhook details should be noted down using the Get Webhook Details endpoint before updating the webhook.

Example Update Webhook Details request:

Copy 
{
    "productId": "123",
    "events": "[101, 102]",
    "config": {
        "url": "https://client_domain.com/webhook",
        "certificateAuthority": "AWS",
        "customHeaders": "{\"key1\": \"value1\", \"key2\": \"value2\", \"key3\": \"value3\"}"
        }
}

If successful, a 200 response is returned with the updated details of the webhook.

For more information, see:

Validate webhook delivery

After enabling AWS signing, confirm that:

  • Webhooks continue to reach your endpoint.

  • Signature verification succeeds.

  • Your endpoint returns the expected HTTP response.

  • There is no unexpected increase in failed deliveries or retries.

Migrate your remaining webhooks

You can migrate webhook registrations individually. Existing and AWS-based signing can coexist during the migration period, so you do not need to move every webhook at the same time.

After all of your webhook registrations have been successfully migrated, you can remove any dependencies in your application that are used only for the previous signing method.

Migration checklist

Before completing your migration, check that you have:

  • Identified all webhook registrations and environments.

  • Obtained the correct Thredd JWKS URL.

  • Added JWKS key retrieval to your webhook receiver.

  • Added key selection using kid.

  • Implemented webhook signature verification.

  • Implemented key caching and refresh behaviour.

  • Tested signature verification in a non-production environment.

  • Confirmed that invalid or modified payloads are rejected.

  • Set certificateAuthority to AWS.

  • Validated webhook delivery after the change.

  • Repeated the migration for each required environment.

For more information on the Webhook authentication process, see the Connecting to Thredd guide.