Skip to content
FRAGMENT
H Webhooks#

FRAGMENT sends an HTTP POST to your server when a Payment event occurs, such as settlement or refund. Create a subscription to register your receiving URL.

Subscriptions

#

Subscription operations follow the API's standard error handling.

Subscribe#

Call createWebhookSubscription with an HTTPS URL. The authenticated API client determines the workspace.

Create a subscription
mutation CreateWebhookSubscription($input: CreateWebhookSubscriptionInput!) {
  createWebhookSubscription(input: $input) {
    __typename
    ... on CreateWebhookSubscriptionResult {
      subscription { id }
      signingSecret
    }
    ... on Error { code message retryable }
  }
}

A subscription receives all event types from every Ledger in its workspace.

Create variables
{
  "input": {
    "url": "https://example.com/webhooks/fragment"
  }
}

Save signingSecret securely on your backend to verify incoming requests. The API returns it only in this response.

ArgumentGraphQL typeRule
input.urlString!Receiving HTTPS URL.

On success, the mutation returns:

Result fieldGraphQL typeMeaning
subscriptionWebhookSubscription!The created subscription.
signingSecretString!Signing secret.

Duplicate URLs

A workspace has one subscription per URL.

  • URLs are compared after normalization, so https://EXAMPLE.com:443/hooks matches https://example.com/hooks.
  • Creating a second subscription for a URL returns BadRequestError with code webhook_subscription_already_exists.
  • To recover a lost signing secret, delete the subscription and create it again.
List subscriptions#

Call webhookSubscriptions to list active subscriptions in the authenticated workspace. Deleted subscriptions are excluded.

List subscriptions
query ListWebhookSubscriptions($first: Int, $after: String) {
  webhookSubscriptions(first: $first, after: $after) {
    nodes {
      id
      url
      created
    }
    pageInfo { endCursor hasNextPage }
  }
}

Listing pages forward only. first defaults to 20 and accepts up to 100. Pass endCursor as after while hasNextPage is true. Each node has the fields below.

Subscription fieldGraphQL type
idID!
urlString!
createdDateTime!
Unsubscribe#

Call deleteWebhookSubscription with the subscription ID. Repeating deletion returns success: true.

Delete a subscription
mutation DeleteWebhookSubscription($id: ID!) {
  deleteWebhookSubscription(id: $id) {
    __typename
    ... on DeleteWebhookSubscriptionResult { success }
    ... on Error { code message retryable }
  }
}

Deletion stops queued deliveries and future retries. A request already in flight may finish. You can create a new subscription at the same URL afterwards. It gets a new ID and signing secret.

On success, the mutation returns:

Result fieldGraphQL typeMeaning
successBoolean!True when the subscription is deleted, including repeated deletion.

Event payload

#

FRAGMENT posts one event per request to the subscription URL. This example shows a settlement notification.

Settlement notification
{
  "type": "payment.settled",
  "id": "example-event-id",
  "occurredAt": "2026-10-27T18:30:00.000Z",
  "data": {
    "workspace": { "id": "example-workspace-id" },
    "ledger": { "id": "example-ledger-id", "ik": "customer-42" },
    "schema": { "key": "invoicing" },
    "payment": { "id": "example-payment-id", "ik": "invoice-1024" },
    "event": {
      "occurredAt": "2026-10-27T18:30:00.000Z",
      "ledgerEntry": { "id": "example-entry-id" }
    }
  }
}

Validate payloads with the JSON Schema. Each event contains these fields.

FieldJSON typeMeaning
idString.Payment event ID; deduplicate within the workspace.
typeString.Event name from the catalog below.
occurredAtISO 8601 string.Source event time, independent of delivery time.
data.workspace{ id: string }Owning workspace.
data.ledger{ id: string, ik: string }Ledger ID and its customer-supplied key.
data.schema{ key: string }Owning Ledger's schema key.
data.payment{ id: string, ik: string }Payment ID and its idempotency key.
data.eventObject.Event-specific fields from the catalog below.

Payment events

#

Every event's data.event carries occurredAt. Each item below lists the fields it adds.

Basic#
  • payment.created: the Payment is created.
  • payment.settled: the Payment settles. Adds ledgerEntry: { id: string }.
Card checkout#
  • payment.checkout: the payer goes through checkout. Adds attempt: { id: string }.
  • payment.retry: you retry the Payment on a saved card. Adds attempt: { id: string }.
  • payment.card_captured: the card network captures the Payment. Adds attempt: { id: string } and ledgerEntry: { id: string } or null.
  • payment.card_declined: the card is declined, or the charge is refused. Adds attempt: { id: string }.
  • payment.card_3ds_canceled: the payer abandons or fails the 3DS check. Adds attempt: { id: string }.
Refunds#
  • payment.refund_initiated: a refund is initiated. Adds refund: { id: string, ik: string } and ledgerEntry: { id: string }.
  • payment.refund_settled: a refund settles. Adds refund: { id: string, ik: string }.
  • payment.refund_failed: a refund fails. Adds refund: { id: string, ik: string } and ledgerEntry: { id: string }.
Disputes#

Dispute events report changes to a card dispute and are in draft. Each also carries dispute: { id: string }. A win's credit is reported by payment.dispute_chargeback_won. A dispute first reported already closed sends its opening and closing events together. Read the Payment for a dispute's current status.

Opening

  • payment.dispute_inquiry_created: an inquiry opens. Adds disputeStatus and responseDueAt.
  • payment.dispute_chargeback_created: a chargeback opens directly and posts chargeback_settled. Adds disputeStatus, responseDueAt and ledgerEntry: { id: string }.
  • payment.dispute_inquiry_escalated: an inquiry becomes a chargeback and posts chargeback_settled. Adds disputeStatus, responseDueAt and ledgerEntry: { id: string }.
  • payment.dispute_prevented: the dispute is resolved before a chargeback opens. Adds disputeStatus and outcome.

Responses

  • payment.dispute_response_due_changed: a response becomes due, or its deadline changes on its own. Opening, escalation, evidence and closure carry their deadline change in their own event. Adds disputeStatus and responseDueAt.
  • payment.dispute_inquiry_evidence_submitted: your inquiry response is submitted. Adds disputeStatus.
  • payment.dispute_chargeback_evidence_submitted: your chargeback evidence is submitted. A saved draft sends none. Adds disputeStatus.
  • payment.dispute_chargeback_accepted: an Admin accepts the chargeback. payment.dispute_chargeback_lost follows when it closes. Adds disputeStatus.

Outcomes

  • payment.dispute_inquiry_closed: an inquiry closes without a chargeback. Adds outcome.
  • payment.dispute_chargeback_won: the bank rules for you, and chargeback_reversed posts. Adds outcome and ledgerEntry: { id: string }.
  • payment.dispute_chargeback_lost: the chargeback closes as lost, by the bank's ruling or because you accepted it. Adds outcome.

Fees and credits

  • payment.dispute_chargeback_fee_assessed: a countered fee is charged and posts chargeback_countered. Adds ledgerEntry: { id: string }.
  • payment.dispute_chargeback_refunded: funds are credited back apart from a win, and chargeback_reversed posts once the dispute has an outcome. Adds ledgerEntry: { id: string }.

Example

A chargeback opening sends:

Chargeback opened
{
  "id": "example-event-id",
  "type": "payment.dispute_chargeback_created",
  "occurredAt": "2026-11-07T14:00:02Z",
  "data": {
    "workspace": { "id": "example-workspace-id" },
    "ledger": { "id": "example-ledger-id", "ik": "main" },
    "schema": { "key": "payments" },
    "payment": { "id": "example-payment-id", "ik": "order-1042" },
    "event": {
      "occurredAt": "2026-11-07T14:00:00Z",
      "dispute": { "id": "example-dispute-id" },
      "ledgerEntry": { "id": "example-entry-id" },
      "disputeStatus": "needs_chargeback_response",
      "responseDueAt": "2026-11-17T23:59:59Z"
    }
  }
}

Verify requests

#

FRAGMENT signs each request following the Standard Webhooks specification. Verify each request with the subscription's signingSecret before processing its event. The Node SDK does this with verifyWebhook, which checks the signature, validates the body, and returns a typed event. Pass it the raw request body, before any JSON parsing. Event types your SDK version does not know about come back with known: false.

Verify and handle an event
import express from "express";
import { match } from "ts-pattern";
import {
  verifyWebhook,
  WebhookVerificationError,
} from "@fragment-dev/node-client";

const app = express();

app.post(
  "/fragment/webhooks",
  express.raw({ type: "application/json" }),
  (req, res) => {
    try {
      const verified = verifyWebhook({
        payload: req.body,
        headers: req.headers,
        secret: process.env.FRAGMENT_WEBHOOK_SECRET!,
      });
      match(verified)
        .with({ known: false }, ({ event }) => {
          console.log(`Ignoring ${event.type}`);
        })
        .with(
          { known: true, event: { type: "payment.settled" } },
          ({ event }) => {
            console.log(`Payment ${event.data.payment.ik} settled`);
          },
        )
        .with({ known: true }, ({ event }) => {
          console.log(`Received ${event.type}`);
        })
        .exhaustive();
      res.sendStatus(200);
    } catch (error) {
      if (error instanceof WebhookVerificationError) {
        res.status(400).send(error.code);
        return;
      }
      throw error;
    }
  },
);

This example uses ts-pattern to handle every event type. An SDK upgrade can ship with new event types, which breaks code that requires all of them to be handled.

Without the SDK#

Each request carries three headers. The signature is an HMAC-SHA256 over the message ID, the timestamp and the body:

HeaderValue
webhook-idMessage ID, unchanged across retries. It can differ from the event id in the body.
webhook-timestampDelivery attempt time, in Unix seconds. Each retry uses the current time.
webhook-signatureSpace-separated signatures, each formatted as v1,<base64-encoded signature>.

Verify against the raw request body before parsing JSON. Reject requests with an invalid signature or a timestamp more than five minutes from your server's time. Check webhook-timestamp, rather than the body's occurredAt. See Standard Webhooks for signing and verification details and verification libraries.

Respond to events

#

Return HTTP 2xx after saving the event or finishing processing. FRAGMENT retries requests after a network error, timeout, or non-2xx response. A request times out if your endpoint does not respond within 30 seconds.

After a failed attempt, FRAGMENT waits 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours before each retry, then stops. The last retry is about 27.5 hours after the first attempt.

  • Events can arrive more than once or out of order.
  • Use the workspace ID and event id to avoid processing duplicates.
  • Retries contain the same event body, including its id and occurredAt.
  • Return HTTP 2xx for event types your application does not handle.