> For the complete documentation index, see [llms.txt](https://shinkalabs.gitbook.io/hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://shinkalabs.gitbook.io/hub/andromeda/guides/webhooks.md).

# Webhooks

Webhooks push events to your endpoint instead of making you poll. Each delivery is HMAC-signed, replay-protected, retried on failure, and parked in a dead-letter queue if it cannot be delivered.

{% hint style="info" %}
Webhook endpoints require an API key with the `admin` scope. Exact request and response bodies are in the [OpenAPI spec](https://api.andromedainfra.pro/openapi.json).
{% endhint %}

## Set up an endpoint

Register a URL and the events you want. Andromeda returns a signing secret for that endpoint; store it. You can register more than one endpoint per tenant.

## Verifying a delivery

Each request carries an HMAC signature over the body, plus a timestamp.

1. Reject the request if the timestamp is more than five minutes old (replay window).
2. Recompute the HMAC over the raw body using your endpoint's signing secret.
3. Compare it to the signature header in constant time.
4. Only then parse and act on the payload.

Always verify before doing anything with the payload. Treat an unverified request as hostile.

## Delivery semantics

* **Retries with backoff.** A failed delivery (non-2xx, timeout, connection error) is retried with increasing delay.
* **Dead-letter queue.** After the retry budget is exhausted, the event lands in a dead-letter queue you can inspect, so nothing is silently lost.
* **At-least-once.** A delivery can arrive more than once (a retry after your handler succeeded but the response was lost). Make your handler idempotent: key off the event id.
* **Order is not guaranteed.** Do not assume events arrive in the order they happened; use the event payload to reconstruct state.

## What you get notified about

There are two families of events:

* **Andromeda events** (six canonical types): lifecycle events the platform emits, for example idempotency replays and policy/recovery actions.
* **On-chain events** (four Anchor self-CPI types from Ika): events parsed off the chain by the [IDL-aware listener](/hub/andromeda/guides/future-sign.md) and fanned out to you.

See [Webhook events](/hub/andromeda/api-reference/webhook-events.md) for the catalogue with payload shapes.

## Operational notes

* Return `2xx` quickly. Do the real work asynchronously; long handlers cause timeouts and retries.
* Rotate the signing secret periodically by re-registering the endpoint.
* Use the dead-letter queue as a health signal: a growing queue means your endpoint is failing.


---

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

```
GET https://shinkalabs.gitbook.io/hub/andromeda/guides/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.