Webhooks

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

Event	Sent when
`order.fulfilled`	Every item in the order has been delivered (`fulfillment_status` is `completed`)
`order.partially_fulfilled`	Some, but not all, of the order has been delivered
`order.cancelled`	The order was cancelled before fulfillment
`order.refunded`	The order was fully refunded to your wallet
`order.partially_refunded`	Part of the order was refunded to your wallet and the rest was delivered

An event is sent each time an order’s fulfillment_status changes to one of the statuses above. There is no separate failed event: an order that can’t be fulfilled ends as order.cancelled or order.refunded.

Registering a Webhook

To register a webhook:

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

The URL must use https and resolve to a public IP address. Private, loopback and link-local addresses are rejected, and redirects are not followed.

Webhook Payload Format

All webhook events follow this standard format:

{
  "id": "01kx3mf0v7q2c9s8d1e4h6j0ab",
  "event": "order.fulfilled",
  "timestamp": "2026-10-22T12:00:00+00:00",
  "data": {
    // The order, same shape as the Get Order response
  }
}

Field	Description
`id`	Unique id for this event. It stays the same when a delivery is retried, so use it to skip events you have already processed.
`event`	One of the event names above
`timestamp`	When the request was sent (ISO 8601)
`data`	The order with its items, same shape as Get Order

data reflects the order as it is when the request is sent. If an order changes status again quickly, an earlier event can already show the newer fulfillment_status, so rely on event to know what happened. Each request also includes these headers:

Header	Description
`X-Manastore-Event`	The event name, same as `event` in the body
`X-Manastore-Signature`	Signature for verifying the request, see Verifying Signatures

Example Payloads

Order Fulfilled Event

{
  "id": "01kx3mf0v7q2c9s8d1e4h6j0ab",
  "event": "order.fulfilled",
  "timestamp": "2026-10-22T12:00:00+00:00",
  "data": {
    "id": 12345,
    "ulid": "01j9z3ndektsv4rrffq69g5fav",
    "user_id": 42,
    "order_number": "#12345",
    "transaction_id": "01j9z3ndf0a1b2c3d4e5f6g7h8",
    "fulfillment_status": "completed",
    "payment_status": "completed",
    "subtotal": {
      "amount": "2500",
      "currency": "EUR",
      "formatted": "€25.00",
      "decimal": "25.00",
      "localized_decimal": "25"
    },
    "conversion_fees": {
      "amount": "0",
      "currency": "EUR",
      "formatted": "€0.00",
      "decimal": "0.00",
      "localized_decimal": "0"
    },
    "total": {
      "amount": "2500",
      "currency": "EUR",
      "formatted": "€25.00",
      "decimal": "25.00",
      "localized_decimal": "25"
    },
    "currency": "EUR",
    "progress": 100,
    "items": [
      {
        "id": 67890,
        "variant_name": "EUR 25",
        "product_name": "Sample Gift Card",
        "product_variant_id": 1234,
        "sku": "1234",
        "status": "completed",
        "delivered_quantity": 1,
        "price": {
          "amount": "2500",
          "currency": "EUR",
          "formatted": "€25.00",
          "decimal": "25.00",
          "localized_decimal": "25"
        },
        "currency": "EUR",
        "quantity": 1,
        "conversion_fee": {
          "amount": "0",
          "currency": "EUR",
          "formatted": "€0.00",
          "decimal": "0.00",
          "localized_decimal": "0"
        },
        "discount_amount": {
          "amount": "0",
          "currency": "EUR",
          "formatted": "€0.00",
          "decimal": "0.00",
          "localized_decimal": "0"
        },
        "discount_percentage": "0.00",
        "discounted_price": {
          "amount": "2500",
          "currency": "EUR",
          "formatted": "€25.00",
          "decimal": "25.00",
          "localized_decimal": "25"
        },
        "total_price": {
          "amount": "2500",
          "currency": "EUR",
          "formatted": "€25.00",
          "decimal": "25.00",
          "localized_decimal": "25"
        },
        "created_at": "2026-10-22T11:58:40+00:00",
        "updated_at": "2026-10-22T12:00:00+00:00"
      }
    ],
    "created_at": "2026-10-22T11:58:40+00:00",
    "updated_at": "2026-10-22T12:00:00+00:00",
    "completed_at": "2026-10-22T12:00:00+00:00"
  }
}

The other order events use the same structure with a different event and the matching fulfillment_status (partially_fulfilled, cancelled, refunded or partially_refunded). Once the order is fulfilled, retrieve the codes with the Get Codes endpoint. Webhook payloads never contain codes.

Verifying Signatures

Every request is signed with your webhook signing secret. You can view, copy and rotate it under Account Settings → Webhook → Signing Secret once a webhook URL is saved. The X-Manastore-Signature header looks like this:

X-Manastore-Signature: t=1792670400,v1=5f8a2c...e91b

t is the Unix timestamp when the request was signed
v1 is a hex encoded HMAC SHA-256 of {t}.{raw request body} using your signing secret as the key

To verify a request:

Read the raw request body before parsing it as JSON
Split the header into t and v1
Compute HMAC_SHA256(secret, t + "." + body) and compare it to v1 using a constant-time comparison
Reject the request if the signatures don’t match, or if t is more than 5 minutes old

const crypto = require('crypto');

function verifyManastoreSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;

  return (
    fresh &&
    expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1))
  );
}

function verifyManastoreSignature(string $rawBody, string $header, string $secret): bool
{
    parse_str(str_replace(',', '&', $header), $parts);
    $expected = hash_hmac('sha256', $parts['t'].'.'.$rawBody, $secret);

    return abs(time() - (int) $parts['t']) < 300
        && hash_equals($expected, $parts['v1'] ?? '');
}

import hashlib, hmac, time

def verify_manastore_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(parts["t"])) < 300 and hmac.compare_digest(expected, parts["v1"])

Rotating the secret takes effect immediately, so update your endpoint with the new secret right after rotating.

Retries

A delivery counts as successful when your endpoint returns a 2xx status. Redirects (3xx) are not followed and count as failures. Failed deliveries are retried: a few quick attempts first, then again after about 1 minute, 5 minutes, 15 minutes and 1 hour. Every retry has the same id.

Best Practices

Return Quickly: Return a 2xx response right away and do any heavy processing afterwards
Verify Signatures: Always check X-Manastore-Signature before acting on a webhook
Deduplicate: Use the event id to ignore deliveries you have already handled
Confirm via the API: For anything that moves money or stock on your side, fetch the order from the API before acting
Timeout: Your endpoint must respond within 10 seconds

Overview

Orders

Products

Wallets

Transactions

Other

Webhooks

Webhooks Overview

Webhook Events

Order Events

Registering a Webhook

Webhook Payload Format

Example Payloads

Order Fulfilled Event

Verifying Signatures

Retries

Best Practices

​Webhooks Overview

​Webhook Events

​Order Events

​Registering a Webhook

​Webhook Payload Format

​Example Payloads

​Order Fulfilled Event

​Verifying Signatures

​Retries

​Best Practices

Webhooks Overview

Webhook Events

Order Events

Registering a Webhook

Webhook Payload Format

Example Payloads

Order Fulfilled Event

Verifying Signatures

Retries

Best Practices