> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/adobe-commerce-magento/additional-features/webhook-jwt-authentication.md).

# Webhook JWT Authentication

Webhook JWT Authentication lets the ESW Adobe Commerce extension validate webhook requests by using ESW public keys from JWKS (JSON Web Key Set). This removes the need for static shared credentials and provides a more secure and scalable authentication model.

JWT validation through JWKS is the default and recommended approach. Basic Auth can still be used as a fallback if it is enabled.

### Supported webhooks

JWT-based authentication applies to these ESW webhook types:

* Order Confirmation
* Inventory Updates
* Returns
* Appeasements
* Cancellations

### How the feature works

The extension fetches ESW public keys from the JWKS endpoint and stores them locally for webhook validation.

The key management flow works like this:

* a scheduled cron job fetches the latest JWKS keys once per day
* fetched keys are stored in the Adobe Commerce flag table
* if validation fails because a key is outdated, the extension can fetch keys again immediately
* a built-in cooldown limits these retry fetches to once per minute

### Webhook validation flow

When Adobe Commerce receives a webhook, the extension validates it in this order:

1. Extract the JWT token from the custom request header.
2. Read the token and identify the matching key ID.
3. Validate the JWT signature with the stored public key.
4. If validation fails because the key may be outdated, fetch the latest key set and retry validation once.
5. If validation still fails and Basic Auth is enabled, fall back to Basic Auth.
6. If the token itself is invalid but the key is valid, reject the request.

{% hint style="info" %}
Basic Auth fallback is only used when enabled and when the failure is related to key validation. It is not used for invalid JWT payloads or invalid token content.
{% endhint %}

### Logging and monitoring

The extension logs key authentication events, including:

* JWT validation attempts
* JWKS key fetches
* retry validation events
* Basic Auth fallback events

To review these logs:

1. Open log filters.
2. Go to **Component → Authentication**.
3. Use **External Request Validation** to isolate related entries.

### Expected result

After setup is complete:

* webhook requests are validated against ESW public keys
* key rotation is handled automatically through JWKS refresh
* fallback behavior is available when Basic Auth is enabled
* authentication issues can be traced through extension logs


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.esw.com/adobe-commerce-magento/additional-features/webhook-jwt-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.