> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.yunojuno.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.yunojuno.com/_mcp/server.

# Securing Your Endpoints

There are two separate security jobs for any webhook endpoint:

1. control who is allowed to reach the endpoint at all
2. verify that a request claiming to be from YunoJuno is genuine

You should do both.

## Recommended endpoint protection

YunoJuno supports two practical ways to protect the endpoint itself:

* API headers
* HTTP Basic Auth

We recommend API headers.

## Why we recommend API headers

API headers are usually the better operational choice because they:

* avoid putting credentials into the URL, as URLs appear in user interfaces and can get shared, leading to unintentional leaks
* are easier to rotate cleanly
* work better with reverse proxies, API gateways, and load balancers
* are usually easier to inspect and manage in production

A common pattern is a shared secret header such as:

```text
Authorization: Bearer <your-shared-token>
```

or a dedicated custom header such as:

```text
X-Webhook-Auth: <your-shared-token>
```

## HTTP Basic Auth

HTTP Basic Auth is also supported if your infrastructure expects it.

It is simple and widely understood, but it is usually less flexible than API headers and can be awkward to rotate if the credential is embedded into the endpoint URL or managed in multiple places.

Use it if your environment requires it, not because it is the preferred default.

## Endpoint authentication is not enough on its own

Header auth or Basic Auth only controls whether a request can reach your service.

You should still verify the webhook signature on every request. Signature verification is what proves:

* the request really came from YunoJuno
* the body was not tampered with in transit
* the timestamp is recent enough to reduce replay risk

## Signature headers

Each webhook request includes three signature-related headers:

* `svix-id`
* `svix-timestamp`
* `svix-signature`

YunoJuno also gives you a signing secret for each endpoint in the webhook portal. Keep that secret server-side.

## Verification rules

To verify a request:

1. read the raw request body exactly as received
2. build the signed content as `{svix-id}.{svix-timestamp}.{raw_body}`
3. calculate an HMAC-SHA256 signature using your endpoint signing secret
4. compare your calculated signature against the values in `svix-signature`
5. reject the request if the timestamp is too old for your tolerance window

## Raw body matters

Do not parse and re-serialize the JSON before verification.

Signature verification must use the exact raw body bytes that arrived over HTTP. If your framework automatically parses JSON for you, make sure the webhook route reads the raw body before any transformation happens.

## Manual verification shape

This is the core logic:

```text
signed_content = svix-id + "." + svix-timestamp + "." + raw_body
expected_signature = base64(hmac_sha256(secret, signed_content))
```

The `svix-signature` header can contain multiple signatures. Your calculated value only needs to match one of them.

## Timestamp checks

You should also check that `svix-timestamp` is within a small tolerance window of your current system time.

That protects you against replay of old requests. A five minute tolerance is a sensible default for most integrations.

## Response handling

If authentication or signature verification fails, return a non-`2xx` response and log the reason internally.

If verification succeeds, acknowledge the request with a `2xx` response as soon as the event has been safely accepted by your system. Do not hold the HTTP response open while long-running downstream work completes.

## Recommended production pattern

For most integrations, the best setup is:

* HTTPS endpoint
* API header authentication
* signature verification on every request
* idempotent event handling keyed by the webhook message ID
* fast `2xx` acknowledgement once the message is safely queued or persisted

That combination is the most robust pattern for both security and delivery reliability.