Webhooks
Register webhook endpoints, receive events over HTTP / Express, and verify their signatures.
Webhooks tell your server when a payment's status changes, so you don't have to poll. This page covers registering endpoints and verifying that incoming events are genuine.
Two halves: registering endpoints (server CRUD) and receiving events
(the listener + handlers). client.webhooks does both.
Register & manage endpoints
import { WebhookEventType } from '@cosmosapp/pay_sdk';
const endpoint = await client.webhooks.create({
url: 'https://me.example.com/hooks/cosmos',
description: 'Production events',
eventTypes: [
WebhookEventType.PaymentIntentSucceeded,
WebhookEventType.PaymentIntentFailed,
], // omit/empty → receive ALL events
});
console.log(endpoint.secret); // whsec_… — returned ONCE, store it now!
await endpoint.disable(); // pause
await endpoint.enable(); // resume
await endpoint.edit({ url: 'https://new...' });
await endpoint.ping(); // send a test event
const rotated = await endpoint.rotateSecret(); // new instance carries new secret
await endpoint.delete();
// audit trail + manual redelivery
const deliveries = await endpoint.fetchDeliveries({ status: 'FAILED', take: 50 });
for (const d of deliveries.items) await d.redeliver();Manager forms exist too: client.webhooks.list(), .fetch(id),
.update(id, {...}), .delete(id), .rotateSecret(id), .ping(id),
.fetchDeliveries(id, {...}), .redeliver(id, deliveryId).
Receive events — client.webhooks.on(...)
Subscribe with the raw type, the camelCase alias, or event for all:
client.webhooks.on('paymentIntentSucceeded', (event) => {
console.log('Paid!', event.data.id, event.data.amount);
});
client.webhooks.on('PAYMENT_INTENT_FAILED', (event) => { /* ... */ });
client.webhooks.on('event', (event) => console.log(event.type));Set the signing secret on the client (or pass { secret } to the handler):
const client = new Client({
apiKey: process.env.COSMOS_PAY_API_KEY,
webhookSecret: process.env.COSMOS_WEBHOOK_SECRET, // whsec_…
});Node.js http (zero deps)
import { createServer } from 'node:http';
createServer(client.webhooks.createHandler()).listen(4242);
// verifies signature → emits event → replies 200 (or 400 on bad signature)Express
import express from 'express';
const app = express();
app.post(
'/hooks/cosmos',
express.raw({ type: '*/*' }), // MUST be the RAW body
client.webhooks.middleware(),
(req, res) => res.sendStatus(200), // req.cosmosEvent is the verified event
);Verify signatures manually
The dispatcher signs each POST with X-Cosmos-Signature: t=<unixSeconds>,v1=<hmacSha256>.
import { Webhooks } from '@cosmosapp/pay_sdk';
Webhooks.verify(rawBody, header, secret); // → true or throws
const event = Webhooks.constructEvent(rawBody, header, secret); // verify + parse
// both accept { toleranceSeconds } (default 300s replay window; 0 disables)
// or on a client (also emits to your on(...) listeners):
client.webhooks.process(rawBody, header, { secret });Bad signatures throw WebhookSignatureError.
Event payload shape
interface WebhookEvent {
id: string; // stable — use for idempotency
type: WebhookEventType;
createdAt: string;
data: PaymentIntentData;
}Event types (WebhookEventType, the same list the API accepts in eventTypes):
- Payment intents:
PAYMENT_INTENT_CREATED,PAYMENT_INTENT_UPDATED,PAYMENT_INTENT_SUCCEEDED,PAYMENT_INTENT_FAILED,PAYMENT_INTENT_CANCELLED,PAYMENT_INTENT_DELETED. - Private payments:
ZK_PAYMENT_SUCCEEDED(itsdatais a private payment). - Same-chain swaps (Stellar, Solana, Monad):
SWAP_CREATED,SWAP_SUBMITTED,SWAP_SUCCEEDED,SWAP_FAILED,SWAP_EXPIRED. - Cross-chain swaps:
CROSS_CHAIN_SWAP_CREATED,CROSS_CHAIN_SWAP_UPDATED,CROSS_CHAIN_SWAP_SUCCEEDED,CROSS_CHAIN_SWAP_REFUNDED,CROSS_CHAIN_SWAP_FAILED,CROSS_CHAIN_SWAP_EXPIRED. - Liquidity:
LIQUIDITY_CREATED,LIQUIDITY_SUBMITTED,LIQUIDITY_SUCCEEDED,LIQUIDITY_FAILED,LIQUIDITY_EXPIRED. - Fiat ramps:
RECEIVER_UPDATED,PAYIN_CREATED,PAYIN_UPDATED,PAYIN_COMPLETED,PAYOUT_CREATED,PAYOUT_UPDATED,PAYOUT_COMPLETED.
A same-chain swap (SWAP_EXPIRED) or a liquidity operation (LIQUIDITY_EXPIRED) can
still settle if its transaction lands late: the API then sends SWAP_SUCCEEDED or
LIQUIDITY_SUCCEEDED, so treat those two as "not settled yet" rather than final.
References
- Client: The main entry point of the SDK — a single, atomic client that exposes every resource through its own manager — an atomic, single-client design.
- WebhookSignatureError: Thrown when a webhook signature fails verification.