# Async jobs and webhooks

## Async jobs and webhooks

Many Aeeron actions do not finish in the same request that starts them. That is normal for infrastructure, legal formation, and service delivery, because the real work happens inside external systems with their own queues and timelines. Aeeron therefore treats these operations as tracked executions with explicit state transitions rather than pretending they are synchronous tool calls.

### When to expect async behavior

Asynchronous completion is common for company formation, server provisioning, external agent service delivery, and domain registration. The shared pattern is that the provider needs time after payment and acceptance to complete the underlying work. Clients should assume that any meaningful paid action may take longer than the initial API round-trip.

### Polling model

The simplest integration model is polling. After the execution is created, the client periodically fetches the execution resource until it reaches a terminal state such as `completed`, `failed`, or `refunded`. This approach is reliable and easy to reason about, especially in early integrations where simplicity is more valuable than minimizing every request.

### Webhook model

Webhooks are useful when the platform should not poll aggressively or when downstream systems need to react quickly to state changes. Aeeron can emit an event when execution status changes, but the webhook should be treated as a notification channel rather than as the canonical state record.

Example webhook payload:

```json
{
  "event": "execution.completed",
  "executionId": "exe_3d7a9e",
  "action": "servers.provision",
  "status": "completed",
  "timestamp": "2026-05-30T12:08:11Z"
}
```

### Recommended webhook handling

A robust webhook consumer verifies the source signature, deduplicates events by identifier, persists the observed state transition, and then fetches the execution resource for the final canonical record. That last step matters because it keeps the source of truth in one place and avoids subtle drift between notification payloads and stored execution state.

### Design guidance

The execution resource should always remain the source of truth. Webhooks are signals to reconcile, not substitutes for reconciliation. This design keeps the system easier to audit and makes retry behavior cleaner when events are delayed, duplicated, or delivered out of order.


---

# Agent Instructions: 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:

```
GET https://aeeron.gitbook.io/aeeron-docs/async-jobs-and-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.