Fragment APIREST v1

Trust the signature. Reconcile the order.

Webhooks notify your backend when an order completes or fails. Verify the raw body, acknowledge quickly, and use order status as your durable reconciliation path.

Configure events in the dashboard

Add up to five HTTPS webhook endpoints from Dashboard → Webhooks. Add a secret between 8 and 64 characters to enable request signing.

Event	Meaning
`order.completed`	The gift order completed successfully.
`order.failed`	The order reached a terminal failure; error/refund metadata is included.

Webhook payload

{
  "event_type": "order.failed",
  "occurred_at": "2026-09-21T10:30:04Z",
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "order_type": "star",
    "amount": 10.5,
    "created_at": "2026-09-21T10:30:00Z",
    "updated_at": "2026-09-21T10:30:04Z",
    "payload": {
      "username": "alexdev",
      "quantity": 100,
      "wallet_type": "TON"
    },
    "error": {
      "error": "Fragment transaction expired",
      "refunded": true,
      "refund_amount": 10.5,
      "refund_transaction_id": 4821
    }
  }
}

Payloads can be delivered more than once. Make your handler idempotent using X-iStar-Delivery and reconcile by order.id.

Verify the HMAC signature

Header	Value
`X-iStar-Event`	Event name.
`X-iStar-Delivery`	Unique numeric delivery ID.
`X-iStar-Attempt`	Current delivery attempt.
`X-iStar-Signature`	Lowercase hex HMAC-SHA256 digest when a secret is configured.

import crypto from "node:crypto";

export function isValidFragmentWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const left = Buffer.from(expected, "hex");
  const right = Buffer.from(signature ?? "", "hex");
  return left.length === right.length && crypto.timingSafeEqual(left, right);
}

Compute the digest from the exact raw request bytes. Parsing and re-serializing JSON before verification can change the byte sequence and invalidate the signature.

Delivery and retries

Return any 2xx response within 10 seconds. Network failures and responses 408, 425, 429, or 5xx are retried up to three total attempts with exponential backoff. Other 4xx responses are recorded without retry.

Verify and persist the event before starting slow downstream work.
Return 2xx after persistence, then process asynchronously.
Poll GET /orders/{order_id} if delivery is delayed or unavailable.
Use the dashboard delivery log when debugging failed endpoints.