> For the complete documentation index, see [llms.txt](https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/atlaspay-api/secret-rotation-and-signature-verification.md).

# Secret Rotation & Signature Verification

AtlasPay generates a unique signing secret for each webhook endpoint. This secret is used to compute an HMAC-SHA256 signature over the raw request body, allowing your server to verify that the event originated from AtlasPay and has not been tampered with.

**The signing secret is shown only once when the webhook endpoint is created or rotated and must be stored securely. AtlasPay cannot retrieve it after display.**

**Verifying a signature**

Each webhook request includes an AtlasPay-Signature header. The format is:

```
AtlasPay-Signature: t=1710509051,v1=abc123

```

To verify the signature:

* Extract the timestamp (t) and signature (v1) from the header.
* Construct the signed payload string: {timestamp}.{raw\_request\_body}
* Compute HMAC-SHA256 of the signed payload string using your signing secret.
* Compare your computed signature to v1 using a constant-time comparison function.
* Optionally, reject events where the timestamp (t) is more than a few minutes old to mitigate replay attacks.

**Rotating a signing secret**

To maintain security, you should periodically rotate your webhook signing secret. You can initiate rotation by calling the rotation endpoint:

```
POST /webhooks/{id}/rotate-secret

```

When rotation is triggered, AtlasPay:

* Generates a new signing secret and returns it once.
* Retains the previous secret as valid for 24 hours.
* Signs all events with both the current and previous secrets during the overlap window.

**Signature format during rotation**

During the overlap period, the AtlasPay-Signature header contains two signatures:

```
AtlasPay-Signature: t=1710509051,v1=abc123,v0=oldsignature

```

Where:

* `v1` — signature generated using the current secret
* `v0` — signature generated using the previous secret

Your integration must accept a webhook as valid if either v1 or v0 produces a matching signature during the overlap window. Once the 24-hour window expires, v0 is removed and only v1 is included.

**Rotation procedure (zero downtime)**

1. Call `POST /webhooks/{id}/rotate-secret` and securely store the new secret.
2. Update your application to verify against both the old and new secrets.
3. Deploy your updated integration before the 24-hour overlap window closes.
4. After the window expires, remove the old secret from your configuration.


---

# 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://constanza-gobbo.gitbook.io/technical-documentation-portfolio/atlaspay-api/secret-rotation-and-signature-verification.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.