> **Source:** https://knowledge.leegality.com/document-execution/api/security/custom-webhook-headers
> **Site:** Leegality Knowledge Base — https://knowledge.leegality.com
> **About:** Leegality is a document execution platform covering eSigning, stamps, NeSL, workflows, and REST API integration.
> **Navigation:** Every article on this site has a plain-text version at `<article-url>.txt` (this format). To get an index of all articles with their `.txt` links, read: https://knowledge.leegality.com/llms.txt
> **AI Guide:** For instructions on how to navigate this knowledge base as an AI agent, read: https://knowledge.leegality.com/ai-readable.txt

---
# Custom Webhook Headers

When Leegality sends a webhook to your endpoint, your server needs a way to verify the request is genuinely coming from Leegality. Custom webhook headers let you define authentication parameters that Leegality includes in every webhook request — your server checks for these before processing the webhook. This supports a range of authentication methods, from basic username/password to bearer tokens and OAuth2.0.

### Types of Custom Webhook Headers

Leegality supports two types of custom webhook headers:

**Static Headers**
- Fixed key-value pairs that remain unchanged for every webhook callback
- Ideal for API keys, usernames, passwords, and fixed authentication tokens

**Dynamic Headers**
- Values fetched in real time from an API before each webhook call
- Suitable for bearer tokens, OAuth2.0 tokens, or any value that refreshes periodically

## How It Works

1. You share your authentication requirements with Leegality support — for example, a static username and password, or an API endpoint Leegality should call to fetch a bearer token before each webhook
2. Leegality configures them on the backend and provides a **Webhook Profile ID**
3. For every webhook request sent to an invitee with the Profile ID attached, Leegality includes the configured headers
4. Your endpoint validates these headers to confirm the request is from Leegality before processing it

## Configuration

#### Step 1: Prepare Header Information

Email Leegality support at **support@leegality.com** with the following details:

**For Static Headers:**

Provide the key-value pairs to be added to the webhook headers. The key names depend on what your authentication system accepts — for example:

| Key | Value |
|-----|-------|
| `username` | `xyz@abc.com` |
| `password` | `sample_password` |

**For Dynamic Headers:**

Provide the details of the API that Leegality should call to fetch values before each webhook:

- **API Endpoint / URL**
- **Method Type** (GET, POST, etc.)
- **Request parameters** — keys, values, and structure
- **Response structure** — the JSON path of the value to extract (e.g., `$.resp_type.code.token`)

Then provide the header mapping — the key name to use in the webhook header and the JSON path pointing to where Leegality should extract the value from the API response. Both the key name and the value source are defined by you:

| Key | Source |
|-----|--------|
| `your-header-key` | `$.resp_type.code.token` *(extracted from API response (JSON) on each call)* |

#### Step 2: Receive Webhook Profile ID

Once Leegality configures your request, you will receive a **Webhook Profile ID**. You need to include this Profile ID with each invitee when sending documents — only invitations with the Profile ID attached will have the custom headers added to their webhook calls.

#### Step 3: Configure Profile ID

1. When creating or editing a workflow, navigate to invitee configuration
2. Go to **Invitee Level Options** for the invitee(s) who should receive custom headers
3. Under **Add custom URLs and webhooks** section
4. Enter the Webhook Profile ID in the **Webhook Profile ID** field

> **Tip — Authenticate Webhook Calls**
>
> When your endpoint receives a webhook from Leegality, validate the custom headers before processing the request. If the headers are missing or do not match your expected values, reject the request. This ensures only legitimate webhook calls from Leegality are processed.