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.
Call createWebhookSubscription with an HTTPS URL. The authenticated API client determines the workspace.
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.
{
"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.
| Argument | GraphQL type | Rule |
|---|---|---|
input.url | String! | Receiving HTTPS URL. |
On success, the mutation returns:
| Result field | GraphQL type | Meaning |
|---|---|---|
subscription | WebhookSubscription! | The created subscription. |
signingSecret | String! | Signing secret. |
Duplicate URLs
A workspace has one subscription per URL.
- URLs are compared after normalization, so
https://EXAMPLE.com:443/hooksmatcheshttps://example.com/hooks. - Creating a second subscription for a URL returns
BadRequestErrorwith codewebhook_subscription_already_exists. - To recover a lost signing secret, delete the subscription and create it again.
Call webhookSubscriptions to list active subscriptions in the authenticated workspace. Deleted subscriptions are excluded.
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 field | GraphQL type |
|---|---|
id | ID! |
url | String! |
created | DateTime! |
Call deleteWebhookSubscription with the subscription ID. Repeating deletion returns success: true.
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 field | GraphQL type | Meaning |
|---|---|---|
success | Boolean! | 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.
{
"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.
| Field | JSON type | Meaning |
|---|---|---|
id | String. | Payment event ID; deduplicate within the workspace. |
type | String. | Event name from the catalog below. |
occurredAt | ISO 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.event | Object. | Event-specific fields from the catalog below. |
Payment events
#Every event's data.event carries occurredAt. Each item below lists the fields it adds.
payment.created: the Payment is created.payment.settled: the Payment settles. AddsledgerEntry: { id: string }.
payment.checkout: the payer goes through checkout. Addsattempt: { id: string }.payment.retry: you retry the Payment on a saved card. Addsattempt: { id: string }.payment.card_captured: the card network captures the Payment. Addsattempt: { id: string }andledgerEntry: { id: string } or null.payment.card_declined: the card is declined, or the charge is refused. Addsattempt: { id: string }.payment.card_3ds_canceled: the payer abandons or fails the 3DS check. Addsattempt: { id: string }.
payment.refund_initiated: a refund is initiated. Addsrefund: { id: string, ik: string }andledgerEntry: { id: string }.payment.refund_settled: a refund settles. Addsrefund: { id: string, ik: string }.payment.refund_failed: a refund fails. Addsrefund: { id: string, ik: string }andledgerEntry: { id: string }.
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. AddsdisputeStatusandresponseDueAt.payment.dispute_chargeback_created: a chargeback opens directly and postschargeback_settled. AddsdisputeStatus,responseDueAtandledgerEntry: { id: string }.payment.dispute_inquiry_escalated: an inquiry becomes a chargeback and postschargeback_settled. AddsdisputeStatus,responseDueAtandledgerEntry: { id: string }.payment.dispute_prevented: the dispute is resolved before a chargeback opens. AddsdisputeStatusandoutcome.
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. AddsdisputeStatusandresponseDueAt.payment.dispute_inquiry_evidence_submitted: your inquiry response is submitted. AddsdisputeStatus.payment.dispute_chargeback_evidence_submitted: your chargeback evidence is submitted. A saved draft sends none. AddsdisputeStatus.payment.dispute_chargeback_accepted: an Admin accepts the chargeback.payment.dispute_chargeback_lostfollows when it closes. AddsdisputeStatus.
Outcomes
payment.dispute_inquiry_closed: an inquiry closes without a chargeback. Addsoutcome.payment.dispute_chargeback_won: the bank rules for you, andchargeback_reversedposts. AddsoutcomeandledgerEntry: { id: string }.payment.dispute_chargeback_lost: the chargeback closes as lost, by the bank's ruling or because you accepted it. Addsoutcome.
Fees and credits
payment.dispute_chargeback_fee_assessed: a countered fee is charged and postschargeback_countered. AddsledgerEntry: { id: string }.payment.dispute_chargeback_refunded: funds are credited back apart from a win, andchargeback_reversedposts once the dispute has an outcome. AddsledgerEntry: { id: string }.
Example
A chargeback opening sends:
{
"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.
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.
Each request carries three headers. The signature is an HMAC-SHA256 over the message ID, the timestamp and the body:
| Header | Value |
|---|---|
webhook-id | Message ID, unchanged across retries. It can differ from the event id in the body. |
webhook-timestamp | Delivery attempt time, in Unix seconds. Each retry uses the current time. |
webhook-signature | Space-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
idto avoid processing duplicates. - Retries contain the same event body, including its
idandoccurredAt. - Return HTTP
2xxfor event types your application does not handle.