feat: add webhook verification methods

README.md

@@ -141,6 +141,29 @@ client.hris.directory.list_individuals(
 )
 ```
 
+## Webhook Verification
+
+We provide helper methods for verifying that a webhook request came from Finch, and not a malicious third party.
+
+You can use `finch.webhooks.verify_signature(body: string, headers, secret?) -> None` or `finch.webhooks.unwrap(body: string, headers, secret?) -> Payload`,
+both of which will raise an error if the signature is invalid.
+
+Note that the "body" parameter must be the raw JSON string sent from the server (do not parse it first).
+The `.unwrap()` method can parse this JSON for you into a `Payload` object.
+
+For example, in [FastAPI](https://fastapi.tiangolo.com/):
+
+```py
+@app.post('/my-webhook-handler')
+async def handler(request: Request):
+    body = await request.body()
+    secret = os.environ['FINCH_WEBHOOK_SECRET']  # env var used by default; explicit here.
+    payload = client.webhooks.unwrap(body, request.headers, secret)
+    print(payload)
+
+    return {'ok': True}
+```
+
 ## Handling errors
 
 When the library is unable to connect to the API (e.g., due to network connection problems or a timeout), a subclass of `finch.APIConnectionError` is raised.

api.md

@@ -223,3 +223,10 @@ Methods:
 
 - <code title="post /disconnect">client.account.<a href="./src/finch/resources/account.py">disconnect</a>() -> <a href="./src/finch/types/disconnect_response.py">DisconnectResponse</a></code>
 - <code title="get /introspect">client.account.<a href="./src/finch/resources/account.py">introspect</a>() -> <a href="./src/finch/types/introspection.py">Introspection</a></code>
+
+# Webhooks
+
+Methods:
+
+- <code>client.webhooks.<a href="./src/finch/resources/webhooks.py">unwrap</a>(\*args) -> object</code>
+- <code>client.webhooks.<a href="./src/finch/resources/webhooks.py">verify_signature</a>(\*args) -> None</code>

src/finch/_client.py

@@ -49,17 +49,20 @@ class Finch(SyncAPIClient):
     ats: resources.ATS
     providers: resources.Providers
     account: resources.Account
+    webhooks: resources.Webhooks
 
     # client options
     access_token: str | None
     client_id: str | None
     client_secret: str | None
+    webhook_secret: str | None
 
     def __init__(
         self,
         *,
         client_id: str | None = None,
         client_secret: str | None = None,
+        webhook_secret: str | None = None,
         base_url: Optional[str] = None,
         access_token: Optional[str] = None,
         timeout: Union[float, Timeout, None] = DEFAULT_TIMEOUT,
@@ -87,6 +90,7 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `client_id` from `FINCH_CLIENT_ID`
         - `client_secret` from `FINCH_CLIENT_SECRET`
+        - `webhook_secret` from `FINCH_WEBHOOK_SECRET`
         """
         self.access_token = access_token
 
@@ -96,6 +100,9 @@ def __init__(
         client_secret_envvar = os.environ.get("FINCH_CLIENT_SECRET", None)
         self.client_secret = client_secret or client_secret_envvar or None
 
+        webhook_secret_envvar = os.environ.get("FINCH_WEBHOOK_SECRET", None)
+        self.webhook_secret = webhook_secret or webhook_secret_envvar or None
+
         if base_url is None:
             base_url = f"https://api.tryfinch.com"
 
@@ -116,6 +123,7 @@ def __init__(
         self.ats = resources.ATS(self)
         self.providers = resources.Providers(self)
         self.account = resources.Account(self)
+        self.webhooks = resources.Webhooks(self)
 
     @property
     def qs(self) -> Querystring:
@@ -151,6 +159,7 @@ def copy(
         *,
         client_id: str | None = None,
         client_secret: str | None = None,
+        webhook_secret: str | None = None,
         access_token: str | None = None,
         base_url: str | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
@@ -189,6 +198,7 @@ def copy(
         return self.__class__(
             client_id=client_id or self.client_id,
             client_secret=client_secret or self.client_secret,
+            webhook_secret=webhook_secret or self.webhook_secret,
             base_url=base_url or str(self.base_url),
             access_token=access_token or self.access_token,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
@@ -272,17 +282,20 @@ class AsyncFinch(AsyncAPIClient):
     ats: resources.AsyncATS
     providers: resources.AsyncProviders
     account: resources.AsyncAccount
+    webhooks: resources.AsyncWebhooks
 
     # client options
     access_token: str | None
     client_id: str | None
     client_secret: str | None
+    webhook_secret: str | None
 
     def __init__(
         self,
         *,
         client_id: str | None = None,
         client_secret: str | None = None,
+        webhook_secret: str | None = None,
         base_url: Optional[str] = None,
         access_token: Optional[str] = None,
         timeout: Union[float, Timeout, None] = DEFAULT_TIMEOUT,
@@ -310,6 +323,7 @@ def __init__(
         This automatically infers the following arguments from their corresponding environment variables if they are not provided:
         - `client_id` from `FINCH_CLIENT_ID`
         - `client_secret` from `FINCH_CLIENT_SECRET`
+        - `webhook_secret` from `FINCH_WEBHOOK_SECRET`
         """
         self.access_token = access_token
 
@@ -319,6 +333,9 @@ def __init__(
         client_secret_envvar = os.environ.get("FINCH_CLIENT_SECRET", None)
         self.client_secret = client_secret or client_secret_envvar or None
 
+        webhook_secret_envvar = os.environ.get("FINCH_WEBHOOK_SECRET", None)
+        self.webhook_secret = webhook_secret or webhook_secret_envvar or None
+
         if base_url is None:
             base_url = f"https://api.tryfinch.com"
 
@@ -339,6 +356,7 @@ def __init__(
         self.ats = resources.AsyncATS(self)
         self.providers = resources.AsyncProviders(self)
         self.account = resources.AsyncAccount(self)
+        self.webhooks = resources.AsyncWebhooks(self)
 
     @property
     def qs(self) -> Querystring:
@@ -374,6 +392,7 @@ def copy(
         *,
         client_id: str | None = None,
         client_secret: str | None = None,
+        webhook_secret: str | None = None,
         access_token: str | None = None,
         base_url: str | None = None,
         timeout: float | Timeout | None | NotGiven = NOT_GIVEN,
@@ -412,6 +431,7 @@ def copy(
         return self.__class__(
             client_id=client_id or self.client_id,
             client_secret=client_secret or self.client_secret,
+            webhook_secret=webhook_secret or self.webhook_secret,
             base_url=base_url or str(self.base_url),
             access_token=access_token or self.access_token,
             timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,

src/finch/resources/__init__.py

@@ -3,6 +3,18 @@
 from .ats import ATS, AsyncATS
 from .hris import HRIS, AsyncHRIS
 from .account import Account, AsyncAccount
+from .webhooks import Webhooks, AsyncWebhooks
 from .providers import Providers, AsyncProviders
 
-__all__ = ["HRIS", "AsyncHRIS", "ATS", "AsyncATS", "Providers", "AsyncProviders", "Account", "AsyncAccount"]
+__all__ = [
+    "HRIS",
+    "AsyncHRIS",
+    "ATS",
+    "AsyncATS",
+    "Providers",
+    "AsyncProviders",
+    "Account",
+    "AsyncAccount",
+    "Webhooks",
+    "AsyncWebhooks",
+]