Webhook settings and changelog

Author: KirillSergeevich

examples/verify_webhook_signature.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from linkedapi import (
+    WEBHOOK_SIGNATURE_HEADER,
+    WEBHOOK_SIGNATURE_TIMESTAMP_HEADER,
+    verify_webhook_signature,
+)
+
+
+def verify_request(raw_body: bytes, headers: Mapping[str, str], *, secret: str | None) -> bool:
+    """Pass Flask's request.get_data() or Django's request.body and request.headers."""
+    return verify_webhook_signature(
+        raw_body=raw_body,
+        timestamp=headers.get(WEBHOOK_SIGNATURE_TIMESTAMP_HEADER),
+        signature=headers.get(WEBHOOK_SIGNATURE_HEADER),
+        secret=secret,
+    )

linkedapi/__init__.py

@@ -6,6 +6,7 @@
     AdminWebhooks,
     LinkedApiAdmin,
 )
+from linkedapi.changelog import get_changelog
 from linkedapi.client import LinkedApi
 from linkedapi.config import LinkedApiConfig
 from linkedapi.core import Operation, poll_workflow_result
@@ -79,9 +80,14 @@
 )
 from linkedapi.types import *  # noqa: F403
 from linkedapi.types import __all__ as _types_all
-from linkedapi.webhooks import parse_webhook_event
+from linkedapi.webhooks import (
+    WEBHOOK_SIGNATURE_HEADER,
+    WEBHOOK_SIGNATURE_TIMESTAMP_HEADER,
+    parse_webhook_event,
+    verify_webhook_signature,
+)
 
-__version__ = "1.4.2"
+__version__ = "1.4.3"
 PredefinedOperation = Operation
 
 __all__ = [
@@ -158,8 +164,12 @@
     "SyncNetwork",
     "ThenWorkflowMapper",
     "VoidWorkflowMapper",
+    "WEBHOOK_SIGNATURE_HEADER",
+    "WEBHOOK_SIGNATURE_TIMESTAMP_HEADER",
     "WithdrawConnectionRequest",
     "__version__",
+    "get_changelog",
     "parse_webhook_event",
     "poll_workflow_result",
+    "verify_webhook_signature",
 ]

linkedapi/admin/webhooks.py

@@ -5,10 +5,17 @@
 from linkedapi.errors import LinkedApiError
 from linkedapi.http import HttpClient
 from linkedapi.types.webhooks import (
+    DeleteWebhookHeaderParams,
     DeleteWebhookParams,
     ReplayWebhookDeliveryParams,
+    RevealWebhookSecretParams,
+    RotateWebhookSecretParams,
+    SetWebhookEventsParams,
+    SetWebhookHeaderParams,
+    SetWebhookHeadersParams,
     SetWebhookParams,
     SetWebhookPayloadModeParams,
+    SetWebhookSigningParams,
     WebhookDelivery,
     WebhookSubscription,
 )
@@ -17,8 +24,9 @@
 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.
+    A client may hold at most one active webhook. Its event selectors control which workflow,
+    account, inbox and network events it receives; None selects all events. Test events are
+    always delivered. Signing and custom headers are configured per subscription.
     """
 
     def __init__(self, http_client: HttpClient[Any]) -> None:
@@ -40,6 +48,78 @@ def set_payload_mode(self, params: SetWebhookPayloadModeParams) -> WebhookSubscr
         )
         return WebhookSubscription.model_validate(result["webhook"])
 
+    def set_signing(self, params: SetWebhookSigningParams) -> WebhookSubscription:
+        """Enable or disable signing. Enabling returns the stored secret."""
+        result = self._post_result(
+            "/admin/webhook.setSigning",
+            "Failed to set webhook signing",
+            params,
+        )
+        return WebhookSubscription.model_validate(result["webhook"])
+
+    def set_headers(self, params: SetWebhookHeadersParams) -> WebhookSubscription:
+        """Replace all custom headers. None or an empty dict clears them."""
+        result = self._post_result(
+            "/admin/webhook.setHeaders",
+            "Failed to set webhook headers",
+            params,
+        )
+        return WebhookSubscription.model_validate(result["webhook"])
+
+    def set_header(self, params: SetWebhookHeaderParams) -> WebhookSubscription:
+        """Set one custom header; its name is matched case-insensitively."""
+        result = self._post_result(
+            "/admin/webhook.setHeader",
+            "Failed to set webhook header",
+            params,
+        )
+        return WebhookSubscription.model_validate(result["webhook"])
+
+    def delete_header(self, params: DeleteWebhookHeaderParams) -> WebhookSubscription:
+        """Remove one custom header; its name is matched case-insensitively."""
+        result = self._post_result(
+            "/admin/webhook.deleteHeader",
+            "Failed to delete webhook header",
+            params,
+        )
+        return WebhookSubscription.model_validate(result["webhook"])
+
+    def reveal_secret(self, params: RevealWebhookSecretParams) -> WebhookSubscription:
+        """Return the current signing secret without changing it."""
+        result = self._post_result(
+            "/admin/webhook.revealSecret",
+            "Failed to reveal webhook secret",
+            params,
+        )
+        return WebhookSubscription.model_validate(result["webhook"])
+
+    def rotate_secret(self, params: RotateWebhookSecretParams) -> WebhookSubscription:
+        """Replace the signing secret and return its new value."""
+        result = self._post_result(
+            "/admin/webhook.rotateSecret",
+            "Failed to rotate webhook secret",
+            params,
+        )
+        return WebhookSubscription.model_validate(result["webhook"])
+
+    def set_events(self, params: SetWebhookEventsParams) -> WebhookSubscription:
+        """Select event types or namespace wildcards; None selects all. Tests always deliver."""
+        result = self._post_result(
+            "/admin/webhook.setEvents",
+            "Failed to set webhook events",
+            params,
+        )
+        return WebhookSubscription.model_validate(result["webhook"])
+
+    def event_types(self) -> list[str]:
+        """Return selectable event types in the server's order.
+
+        The catalog excludes webhook.test, which is always delivered.
+        """
+        result = self._post_result("/admin/webhook.eventTypes", "Failed to get webhook event types")
+        event_types: list[str] = result["eventTypes"]
+        return event_types
+
     def delete(self, params: DeleteWebhookParams) -> None:
         self._post_void("/admin/webhook.delete", "Failed to delete webhook", params)
 

linkedapi/changelog.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from datetime import date, datetime
+
+import requests
+
+from linkedapi.errors import LinkedApiError
+from linkedapi.types.changelog import ChangelogResponse
+
+
+def get_changelog(
+    since: str | date | datetime | None = None,
+    *,
+    url: str = "https://linkedapi.io/api/changelog",
+) -> ChangelogResponse:
+    """Read the public Linked API changelog.
+
+    A release counts as shipped at the end of its week, so callers deduplicate by date.
+
+    Raises:
+        LinkedApiError: on a non-2xx response or network failure.
+    """
+    since_value = since.isoformat() if isinstance(since, date) else since
+    try:
+        response = requests.get(
+            url, params={"since": since_value} if since_value is not None else None
+        )
+    except requests.RequestException as error:
+        raise LinkedApiError("httpError", f"Request error: {error}", {"error": error}) from error
+
+    if not 200 <= response.status_code < 300:
+        try:
+            error_data = response.json()
+        except ValueError:
+            error_data = None
+        message = f"HTTP {response.status_code}: {response.reason}"
+        if isinstance(error_data, dict) and isinstance(error_data.get("error"), str):
+            message = error_data["error"]
+        raise LinkedApiError(
+            "httpError",
+            message,
+            {"status": response.status_code, "statusText": response.reason, "url": response.url},
+        )
+
+    return ChangelogResponse.model_validate(response.json())

linkedapi/types/__init__.py

@@ -47,6 +47,7 @@
     serialize_model,
     serialize_value,
 )
+from linkedapi.types.changelog import ChangelogItem, ChangelogRelease, ChangelogResponse
 from linkedapi.types.company import (
     BaseFetchCompanyParams,
     BaseFetchCompanyParamsWide,
@@ -242,17 +243,25 @@
     AccountWebhookEvent,
     AccountWebhookEventData,
     AccountWebhookStatus,
+    DeleteWebhookHeaderParams,
     DeleteWebhookParams,
     MessageWebhookEvent,
     MessageWebhookEventData,
     NetworkWebhookEvent,
     NetworkWebhookEventData,
     ReplayWebhookDeliveryParams,
+    RevealWebhookSecretParams,
+    RotateWebhookSecretParams,
+    SetWebhookEventsParams,
+    SetWebhookHeaderParams,
+    SetWebhookHeadersParams,
     SetWebhookParams,
     SetWebhookPayloadModeParams,
+    SetWebhookSigningParams,
     WebhookDelivery,
     WebhookDeliveryStatus,
     WebhookEvent,
+    WebhookEventSelector,
     WebhookEventType,
     WebhookPayloadMode,
     WebhookSubscription,
@@ -300,6 +309,9 @@
     "BaseFetchPostParamsWide",
     "BillingPeriod",
     "CancelConnectionSessionParams",
+    "ChangelogItem",
+    "ChangelogRelease",
+    "ChangelogResponse",
     "CheckConnectionStatusParams",
     "CheckConnectionStatusResult",
     "Comment",
@@ -327,6 +339,7 @@
     "CreateRepostResult",
     "DeleteLimitEntry",
     "DeleteLimitsParams",
+    "DeleteWebhookHeaderParams",
     "DeleteWebhookParams",
     "DisconnectParams",
     "EmploymentType",
@@ -456,6 +469,8 @@
     "RetrievePerformanceResult",
     "RetrieveProfileViewersParams",
     "RetrieveSSIResult",
+    "RevealWebhookSecretParams",
+    "RotateWebhookSecretParams",
     "SalaryPeriod",
     "SearchCompaniesFilter",
     "SearchCompaniesParams",
@@ -485,8 +500,12 @@
     "SetSeatsParams",
     "SetSeatsResult",
     "SetSeatsStatus",
+    "SetWebhookEventsParams",
+    "SetWebhookHeaderParams",
+    "SetWebhookHeadersParams",
     "SetWebhookParams",
     "SetWebhookPayloadModeParams",
+    "SetWebhookSigningParams",
     "StCompanyDm",
     "StCompanyEmployee",
     "StCompanyEmployeesFilter",
@@ -502,6 +521,7 @@
     "WebhookDelivery",
     "WebhookDeliveryStatus",
     "WebhookEvent",
+    "WebhookEventSelector",
     "WebhookEventType",
     "WebhookPayloadMode",
     "WebhookSubscription",

linkedapi/types/changelog.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from linkedapi.types.base import LinkedApiModel
+
+
+class ChangelogItem(LinkedApiModel):
+    title: str
+    body: str
+    docs: str
+
+
+class ChangelogRelease(LinkedApiModel):
+    date: str
+    items: list[ChangelogItem]
+
+
+class ChangelogResponse(LinkedApiModel):
+    since: str | None
+    count: int
+    entries: list[ChangelogRelease]