Add admin webhook commands

Author: LordOfTheVillage

examples/webhooks.ts

@@ -0,0 +1,67 @@
+import { LinkedApiAdmin, LinkedApiError, parseWebhookEvent } from '@linkedapi/node';
+import express from 'express';
+
+// 1. Register a webhook and inspect deliveries via the admin client.
+async function manageWebhook(): Promise<void> {
+  const admin = new LinkedApiAdmin({
+    linkedApiToken: process.env.LINKED_API_TOKEN!,
+  });
+
+  try {
+    console.log('🚀 Registering webhook...');
+
+    const webhook = await admin.webhooks.set({
+      url: 'https://example.com/hooks/linkedapi',
+      payloadMode: 'fat',
+    });
+    console.log(`✅ Webhook ${webhook.id} → ${webhook.url}`);
+
+    // Verify the endpoint end-to-end without waiting for a real event.
+    await admin.webhooks.sendTest();
+
+    const deliveries = await admin.webhooks.deliveries();
+    console.log(`📬 Recent deliveries: ${deliveries.length}`);
+    for (const delivery of deliveries) {
+      console.log(`   ${delivery.eventType} → ${delivery.status} (attempts: ${delivery.attempts})`);
+    }
+  } catch (error) {
+    if (error instanceof LinkedApiError) {
+      console.error('🚨 Linked API Error:', error.message);
+    } else {
+      console.error('💥 Unknown error:', error);
+    }
+  }
+}
+
+// 2. Receive events. Capture the RAW body so the payload is parsed exactly as delivered.
+function startReceiver(): void {
+  const app = express();
+  app.use(express.raw({ type: 'application/json' }));
+
+  app.post('/hooks/linkedapi', (req, res) => {
+    const event = parseWebhookEvent(req.body as Buffer);
+
+    switch (event.type) {
+      case 'workflow.completed':
+        console.log(`Workflow ${event.data.workflowId} finished: ${event.data.status}`);
+        console.log('Result:', event.data.result);
+        break;
+      case 'account.reconnectionRequired':
+        console.log(`Account ${event.data.accountId} needs reconnection — pause campaigns.`);
+        break;
+      case 'webhook.test':
+        console.log('Test event received:', event.data.message);
+        break;
+      default:
+        console.log(`Event ${event.type}`);
+    }
+
+    // Acknowledge fast (2xx). Non-2xx makes Linked API retry with backoff.
+    res.sendStatus(200);
+  });
+
+  app.listen(3000, () => console.log('👂 Listening for webhooks on :3000'));
+}
+
+void manageWebhook();
+startReceiver();

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linkedapi/node",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "description": "Control your LinkedIn accounts and retrieve real-time data, all through this Node.js SDK.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/admin/admin-webhooks.ts

@@ -0,0 +1,110 @@
+import {
+  HttpClient,
+  LinkedApiError,
+  TDeleteWebhookParams,
+  TLinkedApiErrorType,
+  TReplayWebhookDeliveryParams,
+  TSetWebhookParams,
+  TSetWebhookPayloadModeParams,
+  TWebhookDelivery,
+  TWebhookSubscription,
+} from '../types';
+
+/**
+ * Manage the client's registered outbound webhook and inspect recent deliveries.
+ *
+ * A client may hold at most one active webhook. It receives every event Linked API emits
+ * (workflow lifecycle + account status changes); filter by the event `type` on your receiver.
+ *
+ * @see {@link https://linkedapi.io/docs/ Linked API Documentation}
+ */
+export class AdminWebhooks {
+  constructor(private readonly httpClient: HttpClient) {}
+
+  public async set(params: TSetWebhookParams): Promise<TWebhookSubscription> {
+    const response = await this.httpClient.post<{ webhook: TWebhookSubscription }>(
+      '/admin/webhook.set',
+      params,
+    );
+    if (response.success && response.result) {
+      return response.result.webhook;
+    }
+    throw new LinkedApiError(
+      (response.error?.type ?? 'httpError') as TLinkedApiErrorType,
+      response.error?.message ?? 'Failed to set webhook',
+    );
+  }
+
+  public async get(): Promise<Array<TWebhookSubscription>> {
+    const response = await this.httpClient.post<{ webhooks: Array<TWebhookSubscription> }>(
+      '/admin/webhook.get',
+    );
+    if (response.success && response.result) {
+      return response.result.webhooks;
+    }
+    throw new LinkedApiError(
+      (response.error?.type ?? 'httpError') as TLinkedApiErrorType,
+      response.error?.message ?? 'Failed to get webhooks',
+    );
+  }
+
+  public async setPayloadMode(params: TSetWebhookPayloadModeParams): Promise<TWebhookSubscription> {
+    const response = await this.httpClient.post<{ webhook: TWebhookSubscription }>(
+      '/admin/webhook.setPayloadMode',
+      params,
+    );
+    if (response.success && response.result) {
+      return response.result.webhook;
+    }
+    throw new LinkedApiError(
+      (response.error?.type ?? 'httpError') as TLinkedApiErrorType,
+      response.error?.message ?? 'Failed to set webhook payload mode',
+    );
+  }
+
+  public async delete(params: TDeleteWebhookParams): Promise<void> {
+    const response = await this.httpClient.post('/admin/webhook.delete', params);
+    if (response.success) {
+      return;
+    }
+    throw new LinkedApiError(
+      (response.error?.type ?? 'httpError') as TLinkedApiErrorType,
+      response.error?.message ?? 'Failed to delete webhook',
+    );
+  }
+
+  public async deliveries(): Promise<Array<TWebhookDelivery>> {
+    const response = await this.httpClient.post<{ deliveries: Array<TWebhookDelivery> }>(
+      '/admin/webhook.deliveries',
+    );
+    if (response.success && response.result) {
+      return response.result.deliveries;
+    }
+    throw new LinkedApiError(
+      (response.error?.type ?? 'httpError') as TLinkedApiErrorType,
+      response.error?.message ?? 'Failed to get webhook deliveries',
+    );
+  }
+
+  public async replayDelivery(params: TReplayWebhookDeliveryParams): Promise<void> {
+    const response = await this.httpClient.post('/admin/webhook.replayDelivery', params);
+    if (response.success) {
+      return;
+    }
+    throw new LinkedApiError(
+      (response.error?.type ?? 'httpError') as TLinkedApiErrorType,
+      response.error?.message ?? 'Failed to replay webhook delivery',
+    );
+  }
+
+  public async sendTest(): Promise<void> {
+    const response = await this.httpClient.post('/admin/webhook.sendTest');
+    if (response.success) {
+      return;
+    }
+    throw new LinkedApiError(
+      (response.error?.type ?? 'httpError') as TLinkedApiErrorType,
+      response.error?.message ?? 'Failed to send test webhook',
+    );
+  }
+}

src/admin/index.ts

@@ -5,6 +5,7 @@ import { AdminAccounts } from './admin-accounts';
 import { buildAdminHttpClient } from './admin-http-client';
 import { AdminLimits } from './admin-limits';
 import { AdminSubscription } from './admin-subscription';
+import { AdminWebhooks } from './admin-webhooks';
 
 /**
  * LinkedApiAdmin - Admin SDK for managing Linked API subscription, accounts, and limits.
@@ -25,12 +26,14 @@ import { AdminSubscription } from './admin-subscription';
  * const status = await admin.subscription.getStatus();
  * const { accounts } = await admin.accounts.getAll();
  * const { limits } = await admin.limits.getDefaults();
+ * const webhook = await admin.webhooks.set({ url: 'https://example.com/hooks' });
  * ```
  */
 export class LinkedApiAdmin {
   public readonly subscription: AdminSubscription;
   public readonly accounts: AdminAccounts;
   public readonly limits: AdminLimits;
+  public readonly webhooks: AdminWebhooks;
 
   constructor(config: TAdminConfig | HttpClient) {
     const httpClient =
@@ -39,5 +42,6 @@ export class LinkedApiAdmin {
     this.subscription = new AdminSubscription(httpClient);
     this.accounts = new AdminAccounts(httpClient);
     this.limits = new AdminLimits(httpClient);
+    this.webhooks = new AdminWebhooks(httpClient);
   }
 }

src/index.ts

@@ -1206,3 +1206,4 @@ export type {
 export * from './types';
 export * from './operations';
 export * from './core/operation';
+export * from './webhooks';

src/types/index.ts

@@ -5,6 +5,7 @@ export * from './responses';
 export * from './workflow-in-progress-response.type';
 export * from './workflow-started-response.type';
 export * from './workflows';
+export * from './webhooks';
 export * from './actions/index';
 export * from './http-client';
 export * from './admin/index';

src/types/webhooks.ts

@@ -0,0 +1,89 @@
+export type TWebhookPayloadMode = 'thin' | 'fat';
+
+export type TWebhookEventType =
+  | 'workflow.created'
+  | 'workflow.started'
+  | 'workflow.completed'
+  | 'account.active'
+  | 'account.reconnectionRequired'
+  | 'account.frozen'
+  | 'account.deleted'
+  | 'webhook.test';
+
+export type TWebhookDeliveryStatus = 'pending' | 'delivering' | 'success' | 'failed';
+
+export type TWorkflowWebhookStatus = 'pending' | 'running' | 'completed' | 'failed';
+
+export type TAccountWebhookStatus = 'active' | 'reconnection_required' | 'frozen' | 'deleted';
+
+export interface TWebhookSubscription {
+  id: string;
+  url: string;
+  payloadMode: TWebhookPayloadMode;
+  isActive: boolean;
+  createdAt: string;
+}
+
+export interface TWebhookDelivery {
+  id: string;
+  eventType: TWebhookEventType;
+  eventId: string;
+  status: TWebhookDeliveryStatus;
+  attempts: number;
+  responseStatusCode: number | null;
+  lastError: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TSetWebhookParams {
+  url: string;
+  payloadMode?: TWebhookPayloadMode;
+}
+
+export interface TSetWebhookPayloadModeParams {
+  id: string;
+  payloadMode: TWebhookPayloadMode;
+}
+
+export interface TDeleteWebhookParams {
+  id: string;
+}
+
+export interface TReplayWebhookDeliveryParams {
+  deliveryId: string;
+}
+
+interface TWebhookEventBase {
+  id: string;
+  createdAt: string;
+}
+
+export interface TWorkflowWebhookEvent extends TWebhookEventBase {
+  type: 'workflow.created' | 'workflow.started' | 'workflow.completed';
+  data: {
+    workflowId: string;
+    accountId: string;
+    status: TWorkflowWebhookStatus;
+    // Present only on workflow.completed delivered in `fat` payload mode; in `thin` mode fetch the
+    // result via the workflow API by workflowId.
+    result?: unknown;
+  };
+}
+
+export interface TAccountWebhookEvent extends TWebhookEventBase {
+  type: 'account.active' | 'account.reconnectionRequired' | 'account.frozen' | 'account.deleted';
+  data: {
+    accountId: string;
+    status: TAccountWebhookStatus;
+  };
+}
+
+export interface TWebhookTestEvent extends TWebhookEventBase {
+  type: 'webhook.test';
+  data: {
+    message: string;
+  };
+}
+
+export type TWebhookEvent = TWorkflowWebhookEvent | TAccountWebhookEvent | TWebhookTestEvent;

src/webhooks/index.ts

@@ -0,0 +1 @@
+export * from './parse-webhook-event';

src/webhooks/parse-webhook-event.ts

@@ -0,0 +1,39 @@
+import { TWebhookEvent } from '../types';
+
+/**
+ * Parse a raw webhook request body into a typed Linked API event.
+ *
+ * Pass the raw HTTP body (string or Buffer) exactly as received. Discriminate the returned event on
+ * its `type` field to narrow `data`.
+ *
+ * @throws Error when the body is not valid JSON or is missing the `id` / `type` envelope fields.
+ *
+ * @example
+ * ```typescript
+ * const event = parseWebhookEvent(rawBody);
+ * if (event.type === 'workflow.completed') {
+ *   console.log(event.data.workflowId, event.data.result);
+ * }
+ * ```
+ */
+export function parseWebhookEvent(rawBody: string | Buffer): TWebhookEvent {
+  const text = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error('Invalid webhook payload: body is not valid JSON');
+  }
+
+  if (
+    typeof parsed !== 'object' ||
+    parsed === null ||
+    typeof (parsed as { id?: unknown }).id !== 'string' ||
+    typeof (parsed as { type?: unknown }).type !== 'string'
+  ) {
+    throw new Error('Invalid webhook payload: missing "id" or "type"');
+  }
+
+  return parsed as TWebhookEvent;
+}