ApiClient webhooks and WebSocket subscriptions

Webhook methods

All webhook-management methods are signed server-side operations.

Method	Purpose
`listWebhooks(apiSecret)`	Lists webhook subscriptions.
`createWebhook(params, apiSecret)`	Creates a webhook subscription.
`updateWebhook(webhookId, params, apiSecret)`	Updates a webhook subscription.
`deleteWebhook(webhookId, apiSecret)`	Deletes a webhook subscription.

Verify incoming webhooks

@coin-voyage/paykit/server also exports verifyWebhookSignature for the endpoint that receives deliveries. It takes the raw request body, the request headers, and your Webhook Secret, checks CoinVoyage-Webhook-Signature-V2 in constant time, and rejects deliveries whose CoinVoyage-Webhook-Timestamp is too far from the current time. It returns { valid: true, ... } or { valid: false, error: { code, message } } and never throws, so check result.valid.

Option	Default	Description
`toleranceSeconds`	`300`	Maximum allowed difference, in seconds, between the delivery timestamp and the current time.
`allowLegacy`	`false`	Accept a request that carries only the legacy `CoinVoyage-Webhook-Signature` header and no timestamp.

Pass the body exactly as received, before any JSON parsing. For a complete Route Handler, see Verify webhook signatures.

Order-scoped WebSocket subscriptions

subscribeOrderStatus() opens a WebSocket connection for real-time order events. Order-scoped subscriptions authenticate with your API key.

const socket = apiClient.subscribeOrderStatus();

socket.onOpen(() => {
  socket.subscribe("order_123");
});

socket.onMessage((msg) => {
  if (msg.type === "event") {
    console.log(msg.data.event, msg.data.order.status);
  }
});

Organization-wide subscriptions

Organization-wide subscriptions require an authorization signature for GET /ws.

const authorizationSignature = apiClient.generateAuthorizationSignature(
  process.env.COIN_VOYAGE_API_SECRET!,
  "GET",
  "/ws"
);

const socket = apiClient.subscribeOrderStatus({ authorizationSignature });

socket.onOpen(() => {
  socket.subscribeOrg();
});

See the webhook event reference for event identifiers and payloads.

Get started

Core concepts

PayKit

SwapKit

Styling / Theme

Invoices

API integration

Going live

Dashboard

Resources

ApiClient webhooks and WebSocket subscriptions

Webhook methods

Verify incoming webhooks

Order-scoped WebSocket subscriptions

Organization-wide subscriptions

​Webhook methods

​Verify incoming webhooks

​Order-scoped WebSocket subscriptions

​Organization-wide subscriptions

Webhook methods

Verify incoming webhooks

Order-scoped WebSocket subscriptions

Organization-wide subscriptions