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:

{
  "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

{
  "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