Webhooks

Webhooks notify your backend when payment, withdrawal, and payout-routing state changes. Use webhooks for real-time updates, then fetch the canonical PayChain resource before releasing value.

Source of truth: A webhook tells you an event happened. The invoice, withdrawal, or routing record remains the canonical state for fulfillment and reconciliation.

Delivery contract

PayChain webhook delivery is at least once. Events can be retried, manually replayed, duplicated, delayed, or delivered after the underlying invoice, withdrawal, or payout-routing resource has already moved to a later state. Do not assume strict ordering across event families, such as invoice.* before withdrawal.*, or across retries for the same resource. Use these identifiers intentionally:

Top-level id and X-Webhook-ID identify this webhook delivery event. Store this value to ignore duplicate deliveries of the same event.
data.resourceId identifies the changed PayChain resource. It matches data.invoiceId, data.withdrawalId, or data.payoutRoutingId depending on data.resourceType.
data.txHash identifies the on-chain transaction when one exists.
data.clientReference is your own reference when supplied on the original API request.

Treat lifecycle events as state synchronization, not commands. For example, withdrawal.completed means a withdrawal resource reached completed; it must not create or submit another withdrawal in your system.

What webhooks are for

Use webhooks to:

Mark an order as paid.
Release a digital good or service.
Update a customer deposit ledger.
Track withdrawal progress.
Track automated payout routing progress.
Alert your team when payout routing fails or a withdrawal is blocked.

Signature verification

Verify every webhook using the raw request body.

X-Webhook-Signature: ...
X-Webhook-Timestamp: ...
X-Webhook-ID: ...

Raw body note: Do not parse JSON and then re-stringify it before verification. Signature verification must use the exact raw bytes PayChain sent.

Express raw-body example

import express from 'express';
import { verifyWebhookSignature } from '@paychainhq/sdk';

const app = express();

app.post('/paychain/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const valid = verifyWebhookSignature({
    rawBody: req.body,
    signature: req.header('X-Webhook-Signature'),
    timestamp: req.header('X-Webhook-Timestamp'),
    secret: process.env.PAYCHAIN_WEBHOOK_SECRET!,
    toleranceSeconds: 300
  });

  if (!valid) {
    return res.status(400).send('invalid signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));

  // Store event.id or X-Webhook-ID to deduplicate this delivery.
  // Use event.data.resourceId to fetch the canonical PayChain resource.
  // Apply resource state changes idempotently; do not treat lifecycle events as commands.

  return res.sendStatus(200);
});

Next.js route handler example

import { NextResponse } from 'next/server';
import { verifyWebhookSignature } from '@paychainhq/sdk';

export async function POST(request: Request) {
  const rawBody = await request.text();

  const valid = verifyWebhookSignature({
    rawBody,
    signature: request.headers.get('X-Webhook-Signature'),
    timestamp: request.headers.get('X-Webhook-Timestamp'),
    secret: process.env.PAYCHAIN_WEBHOOK_SECRET!,
    toleranceSeconds: 300
  });

  if (!valid) {
    return new NextResponse('invalid signature', { status: 400 });
  }

  const event = JSON.parse(rawBody);

  // Store event.id or X-Webhook-ID to deduplicate this delivery.
  // Use event.data.resourceId to fetch the canonical PayChain resource.
  // Apply resource state changes idempotently; do not treat lifecycle events as commands.

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

Recommended handler flow

Receive the webhook request.
Read the raw body.
Verify the signature and timestamp.
Store the top-level webhook id or X-Webhook-ID and return 2xx for duplicates.
Use data.resourceId and data.resourceType to fetch the canonical invoice, withdrawal, or routing record from PayChain.
Apply resource state transitions idempotently. Do not move a completed local payout back to processing because an older event arrived late.
Treat withdrawal.* events as status updates only. Never create a new withdrawal from a withdrawal.completed webhook.
Return a 2xx response quickly.

Common event families

Event family	Meaning
`invoice.*`	Invoice lifecycle changed.
`withdrawal.*`	Withdrawal lifecycle changed.
`invoice.payout_routing.*`	Automated payout routing lifecycle changed.

Common examples:

invoice.paid
invoice.overpaid
invoice.failed
withdrawal.created
withdrawal.processing
withdrawal.completed
withdrawal.failed
invoice.payout_routing.started
invoice.payout_routing.completed
invoice.payout_routing.failed

Example payloads

Webhook payloads include a webhook delivery ID, event type, business ID, timestamp, and a data object for the resource that changed. The top-level id is the webhook delivery/event ID. The changed resource ID is inside data.id and also in the typed field, such as data.invoiceId or data.withdrawalId. Use event as the canonical event type; type is included as a compatibility alias.

Invoice paid

{
  "id": "evt_01HX...",
  "event": "invoice.paid",
  "type": "invoice.paid",
  "businessId": "biz_123",
  "timestamp": "2026-05-20T12:30:01.000Z",
  "createdAt": "2026-05-20T12:30:00.000Z",
  "data": {
    "id": "inv_123",
    "invoiceId": "inv_123",
    "resourceId": "inv_123",
    "resourceType": "invoice",
    "businessId": "biz_123",
    "status": "paid",
    "state": "completed",
    "txHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "metadata": {
      "orderId": "order_123"
    }
  }
}

Withdrawal completed

{
  "id": "evt_01HY...",
  "event": "withdrawal.completed",
  "type": "withdrawal.completed",
  "businessId": "biz_123",
  "timestamp": "2026-05-20T12:36:01.000Z",
  "createdAt": "2026-05-20T12:36:00.000Z",
  "data": {
    "id": "wd_123",
    "withdrawalId": "wd_123",
    "resourceId": "wd_123",
    "resourceType": "withdrawal",
    "businessId": "biz_123",
    "status": "completed",
    "state": "completed",
    "destination": "0x0000000000000000000000000000000000000000",
    "clientReference": "payout_123",
    "txHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
  }
}

Payout routing failed

{
  "id": "evt_01HZ...",
  "event": "invoice.payout_routing.failed",
  "type": "invoice.payout_routing.failed",
  "businessId": "biz_123",
  "timestamp": "2026-05-20T12:40:01.000Z",
  "createdAt": "2026-05-20T12:40:00.000Z",
  "data": {
    "id": "route_run_123",
    "invoiceId": "inv_123",
    "payoutRoutingId": "route_run_123",
    "resourceId": "route_run_123",
    "resourceType": "invoice_payout_routing",
    "failureReason": "Payout quota exceeded before all recipient legs could be created.",
    "payoutRouteId": "route_123"
  }
}

Fulfillment note: Do not fulfill from the webhook payload alone. Verify the signature, store the event ID, fetch the invoice or withdrawal from PayChain, then apply your business action once.

Retry behavior

If your endpoint does not return a successful response, PayChain retries delivery according to the configured retry policy. Repeated failures eventually move the delivery to a failed state. Retryable failures, manual retries, and manual replays can cause older events to arrive after newer resource states. Return a 2xx response only after your system has accepted the event for processing. If you need more time, store the event and process it asynchronously; do not hold the webhook request open for long-running fulfillment, payout, or customer-notification work.

Manual recovery: Failed webhook events can be retried or replayed from the webhook event APIs where supported. A replay creates a fresh delivery event.

API retry guidance

Use an Idempotency-Key for every mutating API call, including createWithdrawal. If a createWithdrawal request times out or returns a 5xx, retry with the same Idempotency-Key or fetch the existing withdrawal by the returned withdrawalId, your clientReference, or the txHash once available. Do not submit a fresh withdrawal request with a new idempotency key until you have confirmed the original request did not create a withdrawal.

Endpoint management

Use the webhook API to:

Get webhook configuration.
Update the webhook URL or enabled state.
Rotate the webhook signing secret.
Send a test webhook.
List webhook events.
Retry or replay failed events.

See OpenAPI reference for the exact endpoint schemas.

Common mistakes

Treating webhook delivery as fulfillment without fetching the canonical resource.
Not storing processed webhook IDs.
Treating withdrawal.completed as a command to create another payout.
Assuming webhook event order matches invoice, sweep, or withdrawal execution order.
Retrying a timed-out createWithdrawal request with a new idempotency key before checking the canonical withdrawal.
Verifying against parsed JSON instead of raw body.
Taking too long before responding.
Using the same webhook URL and secret for sandbox and live.

Start here

Developers

Go live

Webhooks

Webhooks

Delivery contract

What webhooks are for

Signature verification

Express raw-body example

Next.js route handler example

Recommended handler flow

Common event families

Example payloads

Invoice paid

Withdrawal completed

Payout routing failed

Retry behavior

API retry guidance

Endpoint management

Common mistakes

​Webhooks

​Delivery contract

​What webhooks are for

​Signature verification

​Express raw-body example

​Next.js route handler example

​Recommended handler flow

​Common event families

​Example payloads

​Invoice paid

​Withdrawal completed

​Payout routing failed

​Retry behavior

​API retry guidance

​Endpoint management

​Common mistakes

Webhooks

Delivery contract

What webhooks are for

Signature verification

Express raw-body example

Next.js route handler example

Recommended handler flow

Common event families

Example payloads

Invoice paid

Withdrawal completed

Payout routing failed

Retry behavior

API retry guidance

Endpoint management

Common mistakes