@centrali-io/centrali-sdk 5.2.0 → 5.3.0

package/README.md

@@ -898,6 +898,110 @@ await centrali.orchestrations.delete('orch-id');
 | `completed` | Run finished successfully |
 | `failed` | Run failed with error |
 
+### Webhook Subscriptions
+
+Outbound webhooks for record events. Centrali POSTs a signed JSON payload to your URL and records every delivery attempt; failed deliveries retry with backoff and can be replayed or cancelled individually.
+
+```typescript
+import { CentraliSDK, RecordEvents } from '@centrali-io/centrali-sdk';
+
+// Create a subscription — the signing secret is returned ONCE on create
+const { data: sub } = await centrali.webhookSubscriptions.create({
+  name: 'Order notifications',
+  url: 'https://api.example.com/hooks/centrali',
+  events: [RecordEvents.CREATED, RecordEvents.UPDATED],
+  recordSlugs: ['orders'], // omit for all collections
+});
+// `secret` is typed `string | undefined` because reads omit it; create/rotate
+// always populate it, so assert here to keep strict TypeScript happy.
+console.log('Signing secret:', sub.secret!); // copy now — not returned on reads
+```
+
+```typescript
+// Rotate the signing secret (immediate cutover)
+const { data: rotated } = await centrali.webhookSubscriptions.rotateSecret(sub.id);
+console.log('New secret:', rotated.secret!);
+
+// List, update, delete
+const { data: all } = await centrali.webhookSubscriptions.list();
+await centrali.webhookSubscriptions.update(sub.id, { active: false });
+await centrali.webhookSubscriptions.delete(sub.id);
+```
+
+#### Delivery History & Replay
+
+```typescript
+// List deliveries (rows omit requestPayload/responseBody — use .get() for those)
+const deliveries = await centrali.webhookSubscriptions.deliveries.list(sub.id, {
+  status: 'failed',
+  since: new Date(Date.now() - 24 * 60 * 60 * 1000),
+  limit: 50,
+});
+
+// Fetch a single delivery with full payload and response body
+const delivery = await centrali.webhookSubscriptions.deliveries.get(sub.id, deliveryId);
+console.log('Payload:', delivery.data.requestPayload);
+console.log('Response:', delivery.data.httpStatus, delivery.data.responseBody);
+
+// Replay a failed delivery — reuses the original payload and signature
+await centrali.webhookSubscriptions.deliveries.retry(deliveryId);
+
+// Cancel a delivery that is currently retrying
+await centrali.webhookSubscriptions.deliveries.cancel(deliveryId);
+```
+
+#### Event Types
+
+| Event | Emitted When |
+|-------|-------------|
+| `record_created` | A new record is inserted |
+| `record_updated` | An existing record is modified |
+| `record_deleted` | A record is deleted (soft or hard) |
+| `records_bulk_created` | Multiple records are inserted in one batch |
+
+#### Outbound Payload
+
+Centrali POSTs this JSON body to your URL:
+
+```jsonc
+{
+  "event": "record_created",       // 'record_created' | 'record_updated' | 'record_deleted' | 'records_bulk_created'
+  "workspaceSlug": "acme",
+  "recordSlug": "orders",           // collection slug (may be absent on some bulk events)
+  "recordId": "3f2c…-…-…",          // UUID of the affected record
+  "data": { /* record snapshot */ },// present on create/update; absent on delete
+  "timestamp": "2026-04-22T09:31:04.112Z",
+  "createdBy": "user_abc"           // actor — only the field for the matching event
+                                    // (createdBy for create, updatedBy for update, deletedBy for delete)
+}
+```
+
+Verify the signature against the raw bytes of this body **before** parsing it.
+
+#### Signature Verification
+
+Every dispatch includes an `X-Signature` header containing a base64 HMAC-SHA256 of the raw request body. The signing secret has the form `whsec_<base64url>`; strip the prefix and base64url-decode the rest to get the raw key bytes.
+
+```typescript
+import crypto from 'crypto';
+
+function verifyCentraliSignature(rawBody: string, header: string, secret: string): boolean {
+  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64url');
+  const expected = crypto.createHmac('sha256', key).update(rawBody).digest('base64');
+  const received = Buffer.from(header);
+  const expectedBuf = Buffer.from(expected);
+  return received.length === expectedBuf.length && crypto.timingSafeEqual(received, expectedBuf);
+}
+```
+
+#### Delivery Statuses
+
+| Status | Description |
+|--------|-------------|
+| `success` | Endpoint returned 2xx |
+| `retrying` | Awaiting next retry attempt |
+| `failed` | Exhausted all retries, or cancelled |
+
 ## TypeScript Support
 
 The SDK includes full TypeScript definitions for type-safe development: