> 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/idempotency-and-event-handling.md).

# Idempotency & Event Handling

AtlasPay delivers webhook events on an at-least-once basis. The same event may be delivered more than once due to retry logic or transient network failures. Your integration must be idempotent: processing the same event multiple times must produce the same result as processing it once.

**Using event IDs for deduplication**

Each event carries a globally unique id field. AtlasPay guarantees that event IDs are never reused. Use this ID as your deduplication key:

* Before processing an event, check whether its id has already been recorded in your datastore.
* If the ID exists, discard the event and return a 2xx response to AtlasPay immediately.
* If the ID is new, process the event and persist the ID atomically with your business logic (for example, within the same database transaction). A minimal deduplication table needs only two columns: the event ID and a processed timestamp.

AtlasPay does not guarantee that events are delivered in the order they occurred. Your integration must not assume that a payment.updated event, for example, arrives before a payment.succeeded event for the same resource. Design your event handlers to be order-independent. Additionally, because delivery operates on an at-least-once basis, intermediate events may occasionally be missed. Do not rely on receiving every intermediate state transition — always treat the event payload itself as the source of truth for the current state of a resource.


---

# 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/idempotency-and-event-handling.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.