# Webhooks (https://dev.cosmospay.lat/docs/sdk/server/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

```ts
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:

```ts
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):

```ts
const client = new Client({
  apiKey: process.env.COSMOS_PAY_API_KEY,
  webhookSecret: process.env.COSMOS_WEBHOOK_SECRET, // whsec_…
});
```

### Node.js `http` (zero deps)

```ts
import { createServer } from 'node:http';
createServer(client.webhooks.createHandler()).listen(4242);
// verifies signature → emits event → replies 200 (or 400 on bad signature)
```

### Express

```ts
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>`.

```ts
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

```ts
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` (its `data` is 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](https://dev.cosmospay.lat/docs/sdk/definitions/server/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](https://dev.cosmospay.lat/docs/sdk/definitions/server/webhook-signature-error/): Thrown when a webhook signature fails verification.
