> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.manastore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Real-time event notifications for your application

## Webhooks Overview

Webhooks allow your application to receive real-time notifications about important events occurring in Manastore. Instead of polling the API, webhooks push event data directly to your application's endpoint.

## Webhook Events

### Order Events

* **order.fulfilled**: An order has been fulfilled and completed

## Registering a Webhook

To register a webhook:

1. Log in to your Manastore account and navigate to **Account Settings** → **Webhook**
2. Enter your public HTTPS URL endpoint in the webhook URL field
3. Save your settings — Manastore will immediately begin sending events to your endpoint

## Webhook Payload Format

All webhook events follow this standard format:

```json theme={null}
{
  "event": "order.fulfilled",
  "timestamp": "2023-01-01T12:00:00+00:00",
  "data": {
    // Event-specific data
  }
}
```

Note there's no event `id` field. If your handler needs to guard against processing the
same delivery twice (for example after a retry), use `data.id` (the order's own id) rather
than expecting a separate event identifier.

## Example Payloads

### Order Fulfilled Event

```json theme={null}
{
  "event": "order.fulfilled",
  "timestamp": "2023-01-01T12:00:00+00:00",
  "data": {
    "id": 12345,
    "ulid": "01J9Z3NDEKTSV4RRFFQ69G5FAV",
    "order_number": "#ORD-12345",
    "fulfillment_status": "completed",
    "payment_status": "completed",
    "total": {
      "amount": 102.49,
      "formatted": "€102.49"
    }
  }
}
```

## Security

Webhook payloads are **not signed**. There's currently no header you can use to verify a
request genuinely came from Manastore, so treat the webhook as a notification to go check
the order's current state via the API rather than as a trusted source of truth on its own,
particularly for anything that triggers a financial or fulfillment action on your side.

## Best Practices

* **Return Quickly**: Process the webhook and return a 2xx response immediately
* **Retry Logic**: Manastore retries failed webhooks up to 3 times with exponential backoff
* **HTTPS Only**: Webhooks are only sent to HTTPS endpoints
* **Timeout**: Your endpoint must respond within 10 seconds