Webhooks

Webhooks let your server react to things as they happen. When a payment is confirmed, a subscription is canceled, or a customer is updated, StellarTools sends an HTTP POST to your endpoint with a signed JSON payload. Create and manage webhooks at dashboard.stellartools.dev/webhooks. When you create one, pick which events to subscribe to and copy the signing secret to verify deliveries.

Event envelope

Every webhook POST has the same top-level shape, regardless of event type.

{
  "id": "wh_evt_01jx4k...",
  "type": "payment.confirmed",
  "created": "2026-05-01T14:32:00.000Z",
  "livemode": false,
  "data": {
    "object": {
      "id": "pay_01jx4m...",
      "checkout_id": "chk_01jx4n...",
      "customer_id": "cust_01jx2a...",
      "amount": "10 XLM",
      "status": "confirmed",
      "transaction_hash": "a3f92c8d...",
      "created_at": "2026-05-01T14:31:58.000Z",
      "metadata": null
    }
  }
}

Envelope fields

string

required

Unique ID for this event. Prefixed with wh_evt_.

string

required

The event type, e.g. payment.confirmed or subscription.canceled. See the full list below.

string

required

ISO 8601 timestamp of when the event was created.

boolean

required

true if the event came from a mainnet (live) API key. false for testnet.

object

required

Contains the event payload.

Show data fields

object

required

The full resource that triggered the event. Its shape depends on the event type. For payment.* events it is a Payment object, for subscription.* a Subscription, and so on.

object

Only present on *.updated events. Contains the fields that changed, with their previous values. Fields that did not change are not included.For example, on a subscription.updated event where the status changed from active to paused:

"previous_attributes": {
  "status": "active"
}

Event types

Customer events

event

A new customer was created.

event

A customer’s details were updated. Includes previous_attributes.

event

A customer was deleted.

Payment method events

event

A Stellar wallet was linked to a customer.

event

A wallet was removed from a customer.

Checkout events

event

A new checkout session was created.

Payment events

event

A payment transaction was submitted to the network but has not yet been confirmed.

event

A payment is confirmed on the Stellar ledger. This is the event to act on when fulfilling an order.

event

A payment could not be confirmed on-chain.

Refund events

event

A refund was sent to the customer’s wallet successfully.

event

A refund could not be processed.

Subscription events

event

A new subscription was created.

event

A subscription was updated (for example: paused, resumed, or cancel_at_period_end was toggled). Includes previous_attributes.

event

A subscription was canceled.

Handling events

Use st.webhooks.constructEvent to verify the signature and get the typed event back. Always verify before acting on the payload.

import { StellarTools } from "@stellartools/core";
import { NextRequest, NextResponse } from "next/server";

const st = new StellarTools({
  api_key: process.env.STELLAR_TOOLS_API_KEY!,
});

export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = req.headers.get("X-StellarTools-Signature")!;

  const event = st.webhooks.constructEvent(body, signature, process.env.STELLAR_TOOLS_WEBHOOK_SECRET!);

  switch (event.type) {
    case "payment.confirmed": {
      const payment = event.data.object;
      // payment.id, payment.customer_id, payment.amount, payment.transaction_hash
      break;
    }
    case "subscription.updated": {
      const subscription = event.data.object;
      const changed = event.data.previous_attributes;
      // check what changed: changed?.status, changed?.cancel_at_period_end, etc.
      break;
    }
    case "subscription.canceled": {
      const subscription = event.data.object;
      // revoke access for subscription.customer_id
      break;
    }
    case "refund.succeeded": {
      const refund = event.data.object;
      break;
    }
  }

  return NextResponse.json({ received: true });
}

If constructEvent throws, the signature is invalid or the payload was tampered with. Return a 400 and do not process the event.

Retries

If your endpoint returns a non-2xx response, StellarTools will retry the delivery. Check your webhook logs at dashboard.stellartools.dev/webhooks to see all delivery attempts and manually resend any failed events.

Getting Started

Concepts

Integrations

Marketplace

Webhooks

Event envelope

Envelope fields

Event types

Customer events

Payment method events

Checkout events

Payment events

Refund events

Subscription events

Handling events

Retries

​Event envelope

​Envelope fields

​Event types

​Customer events

​Payment method events

​Checkout events

​Payment events

​Refund events

​Subscription events

​Handling events

​Retries

Event envelope

Envelope fields

Event types

Customer events

Payment method events

Checkout events

Payment events

Refund events

Subscription events

Handling events

Retries