Add webhook management and event parsing

LordOfTheVillage · LordOfTheVillage · commit ec886cbcd800 · 2026-07-01T14:42:16.000+03:00
diff --git a/linkedapi/__init__.py b/linkedapi/__init__.py
@@ -3,6 +3,7 @@
     AdminHttpClient,
     AdminLimits,
     AdminSubscription,
+    AdminWebhooks,
     LinkedApiAdmin,
 )
 from linkedapi.client import LinkedApi
@@ -64,8 +65,9 @@
 )
 from linkedapi.types import *  # noqa: F403
 from linkedapi.types import __all__ as _types_all
+from linkedapi.webhooks import parse_webhook_event
 
-__version__ = "1.0.4"
+__version__ = "1.1.0"
 PredefinedOperation = Operation
 
 __all__ = [
@@ -74,6 +76,7 @@
     "AdminHttpClient",
     "AdminLimits",
     "AdminSubscription",
+    "AdminWebhooks",
     "ActionConfig",
     "ArrayWorkflowMapper",
     "BaseMapper",
@@ -129,5 +132,6 @@
     "VoidWorkflowMapper",
     "WithdrawConnectionRequest",
     "__version__",
+    "parse_webhook_event",
     "poll_workflow_result",
 ]
diff --git a/linkedapi/admin/__init__.py b/linkedapi/admin/__init__.py
@@ -3,11 +3,13 @@
 from linkedapi.admin.http_client import AdminHttpClient
 from linkedapi.admin.limits import AdminLimits
 from linkedapi.admin.subscription import AdminSubscription
+from linkedapi.admin.webhooks import AdminWebhooks
 
 __all__ = [
     "AdminAccounts",
     "AdminHttpClient",
     "AdminLimits",
     "AdminSubscription",
+    "AdminWebhooks",
     "LinkedApiAdmin",
 ]
diff --git a/linkedapi/admin/admin.py b/linkedapi/admin/admin.py
@@ -6,12 +6,13 @@
 from linkedapi.admin.http_client import AdminHttpClient
 from linkedapi.admin.limits import AdminLimits
 from linkedapi.admin.subscription import AdminSubscription
+from linkedapi.admin.webhooks import AdminWebhooks
 from linkedapi.http import HttpClient
 from linkedapi.types.admin import AdminConfig
 
 
 class LinkedApiAdmin:
-    """Admin SDK for Linked API subscription, account, and limit management."""
+    """Admin SDK for Linked API subscription, account, limit, and webhook management."""
 
     def __init__(self, config: AdminConfig | HttpClient[Any]) -> None:
         http_client = (
@@ -20,3 +21,4 @@ def __init__(self, config: AdminConfig | HttpClient[Any]) -> None:
         self.subscription = AdminSubscription(http_client)
         self.accounts = AdminAccounts(http_client)
         self.limits = AdminLimits(http_client)
+        self.webhooks = AdminWebhooks(http_client)
diff --git a/linkedapi/admin/webhooks.py b/linkedapi/admin/webhooks.py
@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any
+
+from linkedapi.errors import LinkedApiError
+from linkedapi.http import HttpClient
+from linkedapi.types.webhooks import (
+    DeleteWebhookParams,
+    ReplayWebhookDeliveryParams,
+    SetWebhookParams,
+    SetWebhookPayloadModeParams,
+    WebhookDelivery,
+    WebhookSubscription,
+)
+
+
+class AdminWebhooks:
+    """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.
+    """
+
+    def __init__(self, http_client: HttpClient[Any]) -> None:
+        self.http_client = http_client
+
+    def set(self, params: SetWebhookParams) -> WebhookSubscription:
+        result = self._post_result("/admin/webhook.set", "Failed to set webhook", params)
+        return WebhookSubscription.model_validate(result["webhook"])
+
+    def get(self) -> list[WebhookSubscription]:
+        result = self._post_result("/admin/webhook.get", "Failed to get webhooks")
+        return [WebhookSubscription.model_validate(item) for item in result["webhooks"]]
+
+    def set_payload_mode(self, params: SetWebhookPayloadModeParams) -> WebhookSubscription:
+        result = self._post_result(
+            "/admin/webhook.setPayloadMode",
+            "Failed to set webhook payload mode",
+            params,
+        )
+        return WebhookSubscription.model_validate(result["webhook"])
+
+    def delete(self, params: DeleteWebhookParams) -> None:
+        self._post_void("/admin/webhook.delete", "Failed to delete webhook", params)
+
+    def deliveries(self) -> list[WebhookDelivery]:
+        result = self._post_result("/admin/webhook.deliveries", "Failed to get webhook deliveries")
+        return [WebhookDelivery.model_validate(item) for item in result["deliveries"]]
+
+    def replay_delivery(self, params: ReplayWebhookDeliveryParams) -> None:
+        self._post_void(
+            "/admin/webhook.replayDelivery",
+            "Failed to replay webhook delivery",
+            params,
+        )
+
+    def send_test(self) -> None:
+        self._post_void("/admin/webhook.sendTest", "Failed to send test webhook")
+
+    def _post_result(
+        self,
+        path: str,
+        default_message: str,
+        params: Any | None = None,
+    ) -> dict[str, Any]:
+        response = self.http_client.post(path, params)
+        if response.success and response.result is not None:
+            result: dict[str, Any] = response.result
+            return result
+        raise LinkedApiError(
+            response.error.type if response.error else "httpError",
+            response.error.message if response.error else default_message,
+        )
+
+    def _post_void(self, path: str, default_message: str, params: Any | None = None) -> None:
+        response = self.http_client.post(path, params)
+        if response.success:
+            return
+        raise LinkedApiError(
+            response.error.type if response.error else "httpError",
+            response.error.message if response.error else default_message,
+        )
diff --git a/linkedapi/types/__init__.py b/linkedapi/types/__init__.py
@@ -178,6 +178,26 @@
     RetrievePerformanceResult,
     RetrieveSSIResult,
 )
+from linkedapi.types.webhooks import (
+    AccountWebhookEvent,
+    AccountWebhookEventData,
+    AccountWebhookStatus,
+    DeleteWebhookParams,
+    ReplayWebhookDeliveryParams,
+    SetWebhookParams,
+    SetWebhookPayloadModeParams,
+    WebhookDelivery,
+    WebhookDeliveryStatus,
+    WebhookEvent,
+    WebhookEventType,
+    WebhookPayloadMode,
+    WebhookSubscription,
+    WebhookTestEvent,
+    WebhookTestEventData,
+    WorkflowWebhookEvent,
+    WorkflowWebhookEventData,
+    WorkflowWebhookStatus,
+)
 from linkedapi.types.workflow import (
     LinkedApiActionError,
     WorkflowCancelResponse,
@@ -194,6 +214,9 @@
 
 __all__ = [
     "AccountInfo",
+    "AccountWebhookEvent",
+    "AccountWebhookEventData",
+    "AccountWebhookStatus",
     "AccountsResult",
     "AdminAccount",
     "AdminAccountStatus",
@@ -232,6 +255,7 @@
     "CreateReconnectionSessionResult",
     "DeleteLimitEntry",
     "DeleteLimitsParams",
+    "DeleteWebhookParams",
     "DisconnectParams",
     "EmploymentType",
     "FetchCompanyParams",
@@ -315,6 +339,7 @@
     "RemoveConnectionParams",
     "ReparseAccountInfoParams",
     "ReparseAccountInfoResult",
+    "ReplayWebhookDeliveryParams",
     "ResetLimitsParams",
     "RetrieveConnectionsFilter",
     "RetrieveConnectionsParams",
@@ -341,6 +366,8 @@
     "SetSeatsParams",
     "SetSeatsResult",
     "SetSeatsStatus",
+    "SetWebhookParams",
+    "SetWebhookPayloadModeParams",
     "StCompanyDm",
     "StCompanyEmployee",
     "StCompanyEmployeesFilter",
@@ -350,6 +377,14 @@
     "SubscriptionStatus",
     "SubscriptionStatusValue",
     "SyncConversationParams",
+    "WebhookDelivery",
+    "WebhookDeliveryStatus",
+    "WebhookEvent",
+    "WebhookEventType",
+    "WebhookPayloadMode",
+    "WebhookSubscription",
+    "WebhookTestEvent",
+    "WebhookTestEventData",
     "WithdrawConnectionRequestParams",
     "WorkflowCancelResponse",
     "WorkflowCompletion",
@@ -361,6 +396,9 @@
     "WorkflowResponse",
     "WorkflowStartedResponse",
     "WorkflowStatus",
+    "WorkflowWebhookEvent",
+    "WorkflowWebhookEventData",
+    "WorkflowWebhookStatus",
     "YearsOfExperience",
     "dump_model_by_name",
     "serialize_model",
diff --git a/linkedapi/types/webhooks.py b/linkedapi/types/webhooks.py
@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from linkedapi.types.base import LinkedApiModel
+
+WebhookPayloadMode = Literal["thin", "fat"]
+WebhookEventType = Literal[
+    "workflow.created",
+    "workflow.started",
+    "workflow.completed",
+    "account.active",
+    "account.reconnectionRequired",
+    "account.frozen",
+    "account.deleted",
+    "webhook.test",
+]
+WebhookDeliveryStatus = Literal["pending", "delivering", "success", "failed"]
+WorkflowWebhookStatus = Literal["pending", "running", "completed", "failed"]
+AccountWebhookStatus = Literal["active", "reconnection_required", "frozen", "deleted"]
+
+
+class WebhookSubscription(LinkedApiModel):
+    id: str | None = None
+    url: str | None = None
+    payload_mode: WebhookPayloadMode | None = None
+    is_active: bool | None = None
+    created_at: str | None = None
+
+
+class WebhookDelivery(LinkedApiModel):
+    id: str | None = None
+    event_type: WebhookEventType | None = None
+    event_id: str | None = None
+    status: WebhookDeliveryStatus | None = None
+    attempts: int | None = None
+    response_status_code: int | None = None
+    last_error: str | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class SetWebhookParams(LinkedApiModel):
+    url: str
+    payload_mode: WebhookPayloadMode | None = None
+
+
+class SetWebhookPayloadModeParams(LinkedApiModel):
+    id: str
+    payload_mode: WebhookPayloadMode
+
+
+class DeleteWebhookParams(LinkedApiModel):
+    id: str
+
+
+class ReplayWebhookDeliveryParams(LinkedApiModel):
+    delivery_id: str
+
+
+class WorkflowWebhookEventData(LinkedApiModel):
+    workflow_id: str | None = None
+    account_id: str | None = None
+    status: WorkflowWebhookStatus | None = None
+    # Present only on workflow.completed delivered in `fat` payload mode; in `thin` mode fetch the
+    # result via the workflow API by workflow_id.
+    result: Any | None = None
+
+
+class WorkflowWebhookEvent(LinkedApiModel):
+    id: str
+    type: Literal["workflow.created", "workflow.started", "workflow.completed"]
+    created_at: str | None = None
+    data: WorkflowWebhookEventData
+
+
+class AccountWebhookEventData(LinkedApiModel):
+    account_id: str | None = None
+    status: AccountWebhookStatus | None = None
+
+
+class AccountWebhookEvent(LinkedApiModel):
+    id: str
+    type: Literal[
+        "account.active",
+        "account.reconnectionRequired",
+        "account.frozen",
+        "account.deleted",
+    ]
+    created_at: str | None = None
+    data: AccountWebhookEventData
+
+
+class WebhookTestEventData(LinkedApiModel):
+    message: str | None = None
+
+
+class WebhookTestEvent(LinkedApiModel):
+    id: str
+    type: Literal["webhook.test"]
+    created_at: str | None = None
+    data: WebhookTestEventData
+
+
+WebhookEvent = WorkflowWebhookEvent | AccountWebhookEvent | WebhookTestEvent
diff --git a/linkedapi/webhooks/__init__.py b/linkedapi/webhooks/__init__.py
@@ -0,0 +1,3 @@
+from linkedapi.webhooks.parse import parse_webhook_event
+
+__all__ = ["parse_webhook_event"]
diff --git a/linkedapi/webhooks/parse.py b/linkedapi/webhooks/parse.py
@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+
+from linkedapi.types.webhooks import (
+    AccountWebhookEvent,
+    WebhookEvent,
+    WebhookTestEvent,
+    WorkflowWebhookEvent,
+)
+
+
+def parse_webhook_event(raw_body: str | bytes) -> WebhookEvent:
+    """Parse a raw webhook request body into a typed Linked API event.
+
+    Pass the raw HTTP body (``str`` or ``bytes``) exactly as received, then branch on the
+    returned event's ``type``.
+
+    Raises:
+        ValueError: when the body is not valid JSON or is missing the ``id`` / ``type`` fields,
+            or carries an unknown event type.
+    """
+    text = raw_body.decode("utf-8") if isinstance(raw_body, (bytes, bytearray)) else raw_body
+
+    try:
+        parsed = json.loads(text)
+    except (ValueError, TypeError) as error:
+        msg = "Invalid webhook payload: body is not valid JSON"
+        raise ValueError(msg) from error
+
+    if (
+        not isinstance(parsed, dict)
+        or not isinstance(parsed.get("id"), str)
+        or not isinstance(parsed.get("type"), str)
+    ):
+        msg = 'Invalid webhook payload: missing "id" or "type"'
+        raise ValueError(msg)
+
+    event_type: str = parsed["type"]
+    if event_type.startswith("workflow."):
+        return WorkflowWebhookEvent.model_validate(parsed)
+    if event_type.startswith("account."):
+        return AccountWebhookEvent.model_validate(parsed)
+    if event_type == "webhook.test":
+        return WebhookTestEvent.model_validate(parsed)
+
+    msg = f"Unknown webhook event type: {event_type}"
+    raise ValueError(msg)
diff --git a/pyproject.toml b/pyproject.toml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+from linkedapi.webhooks.parse import parse_webhook_event`
	`2`	`+`
	`3`	`+__all__ = ["parse_webhook_event"]`