python(feat): webhooks resource by Brandon-Shippy · Pull Request #789 · sift-stack/sift

Brandon-Shippy · 2026-09-14T23:54:37Z

Description

Adds a webhooks resource to sift_client, and lets a rule call a webhook when it is violated.

Webhook and all associated classes and enums are made.
Implements get, list_, find, create, update, archive/unarchive, send_test_request

Validation

End to End testing with manual script written to test each new API feature.
Full pipeline tested against a local stack: created a webhook and a rule with a webhook action, streamed points breaking the rule, and confirmed the delivery in the receiving server

github-actions · 2026-09-14T23:56:01Z

Python docs preview: https://sift-stack.github.io/sift/python/pr-789/

Deployed from 21fdb14. The link may take up to a minute to become live as GitHub Pages propagates.

alexluck-sift · 2026-09-16T18:08:20Z

        return cls(int(val))


 class RuleAction(BaseType[RuleActionProto, "RuleAction"]):


This is a pretty inconvenient type to work with and doesn't follow the user-friendly patterns we do with other types. That is using the to_proto to convert to the proto friendly Ids. Can we address this as par tof this PR instead of carrying the tech debt forward?

wei-qlu · 2026-09-20T03:16:11Z

@@ -0,0 +1,62 @@
+"""References to other Sift resources.


Ref[T] is just str | T with a new name to look up. Let's write the union inline like the other models do and drop this

i removed it union is now inline

wei-qlu · 2026-09-20T03:38:53Z

+        return cls(action_type=RuleActionType.WEBHOOK, webhook=webhook)
+
+    @classmethod
+    def for_annotation(


Renaming RuleAction.annotation breaks existing callers. Let's keep it as is and name the new constructor RuleAction.webhook

in general, renaming existing fields is not backwards compatible and can cause unintentional/breaking changes (e.g., rule.action.tags now returns something else

I kept RuleAction.annotation, tags_ids, default_assignee_user, and the tags property

wei-qlu · 2026-09-20T04:04:54Z

+
+#### Webhooks API
+
+New `client.webhooks` resource, and `RuleAction.for_webhook(...)` to attach a webhook to a rule.


make sure the changelog is updated to reflect any changes

added logs for user-visible changes

wei-qlu · 2026-09-20T04:14:56Z

pre-existing, but lets allow asset objects here too (list[str | Asset]) so callers don't need asset._id_or_error

asset_ids now accepts list[str | Asset]

…set in asset_ids

alexluck-sift

Audit pass on the webhooks surface. Nine comments, five of them nits. The first one is the only thing I'd call blocking, and it's a reviewer conflict rather than anything you did wrong.

alexluck-sift · 2026-09-21T20:48:14Z

    annotation_type: RuleAnnotationType | None = None
    tags_ids: list[str] | None = None
    default_assignee_user: str | None = None
+    webhook_id: str | None = None


RuleAction.webhook(wh) accepts an object, but the field it writes only takes a string, so anyone building a RuleAction directly is back to webhook._id_or_error. That's the thing my rule.py:277 thread asked to remove, and asset_ids gained list[str | Asset] 113 lines up in this same commit.

I'd take str | Webhook here and resolve it in _to_update_request. Worth settling with @wei-qlu first, since dropping the Ref alias was right but it took this with it. Same applies to tags_ids and default_assignee_user above, which are pre-existing so out of scope for this PR.

38c50f7

RuleAction.webhook_id now just takes str | Webhook

alexluck-sift · 2026-09-21T20:48:15Z

+    http_headers: list[WebhookHttpHeader]
+    created_date: datetime
+    modified_date: datetime
+    created_by_user_id: str


created_by_user_id, modified_by_user_id and organization_id have no accessor, so finding out who made a webhook is a second call the caller assembles. Rule.assets and Channel.asset are the shape: an ID field plus a property that resolves it.

Add created_by and modified_by backed by client.users. Heads up that the seven existing created_by/organization properties in sift_types/ all raise NotImplementedError, written before the Users resource existed, so they look like precedent and aren't.

added Webhook.created_by and modified_by 38c50f7

alexluck-sift · 2026-09-21T20:48:15Z

+        webhook = await self._low_level_client.get_webhook(webhook_id=webhook_id)
+        return self._apply_client_to_instance(webhook)
+
+    async def list_(


No date ranges and no created_by/modified_by, so "webhooks added last week" isn't expressible. ListWebhooksRequest only filters on webhook_id, name, event_type, is_archived and archived_date, and CONTRIBUTING says a proto that can't serve the standard filter set should be changed rather than worked around.

Add created_date, modified_date, created_by_user_id and modified_by_user_id to the ListWebhooks filter fields, then expose the standard arguments here.

ListWebhooks only supports webhook_id, name, event_type, is_archived, archived_date. Cannot filter this currently. I will make a ticket to fix this

alexluck-sift · 2026-09-21T20:48:15Z

+        grpc_webhook = cast("CreateWebhookResponse", response).webhook
+        return Webhook._from_proto(grpc_webhook)
+
+    async def update_webhook(self, update: WebhookUpdate) -> Webhook:


Two concurrent webhooks.update calls each send a full Webhook here, so the second one reverts the first one's field. This is the only MergeMessage in low_level_wrappers/, and the proto declares a sparse masked patch with seven maskable fields named.

I'd send the patch and mask straight through. If the service genuinely rejects a sparse Webhook, file that as a server bug and link it from here, because the workaround costs a round trip and loses concurrent writes.

Server-side bug. Making a ticket and will triage. UpdateWebhook cannot accept a partial webhook. So, it reads the webhook before writing the update. Concurrent webhooks will overwrite each other.

alexluck-sift · 2026-09-21T20:48:15Z

+        """
+        return await self.update(webhook, WebhookUpdate(is_archived=False))
+
+    async def test(


nit: this sends a real HTTP request to a customer endpoint, and test reads like the opposite to anyone scanning autocomplete, on top of colliding with test-suite vocabulary. webhook is also optional and positional, which fixes the parameter position permanently.

I'd go with send_test_request and move webhook behind the *. The rename touches sift_types/webhook.py and the sync stubs, so it needs doing by hand.

renamed test to send_test_request 38c50f7

alexluck-sift · 2026-09-21T20:48:15Z

+class WebhookEventType(Enum):
+    """Enum for the events that trigger a webhook."""
+
+    UNSPECIFIED = WebhookEventTypeProto.WEBHOOK_EVENT_TYPE_UNSPECIFIED  # 0


nit: WEBHOOK_EVENT_TYPE_UNSPECIFIED is the proto's zero value and never something a caller should pass. No other enum in sift_types/ exposes its unspecified member.

Drop it and map an unset event_type to None in _from_proto.

dropped and maps properly now 38c50f7

alexluck-sift · 2026-09-21T20:48:15Z

+    """
+
+    http_response_code: int
+    http_response_body: bytes


nit: bytes is the right call for the field, since the body comes from an arbitrary endpoint and may not be text at all, but it leaves every caller writing the same decode.

Add a text property returning self.http_response_body.decode(errors="replace"), matching AnnotationCommentElement.text in #792.

added WebhookTestResult.text 38c50f7

alexluck-sift · 2026-09-21T20:48:15Z

+        return cls(name=proto.name, value=proto.value)
+
+
+class WebhookTestResult(BaseModel):


nit: this is the library's first struct returned from a method, and #793 is adding a second one the same week with a different suffix, UserDefinedFunctionValidation.

No strong view on which wins, but the two PRs should agree. If *Result stays here, #793 wants UserDefinedFunctionValidationResult.

dc8d34e

Decided on dropping the suffix

alexluck-sift · 2026-09-21T20:48:15Z

+        return value
+
+    @model_validator(mode="after")
+    def _validate_target_url(self):


nit: this validator sits on WebhookBase, which doesn't declare target_url, so it reads through getattr(self, "target_url", None). Rename the field on either subclass and validation silently passes everything, with a bad URL only failing at the server.

Declare target_url: str | None = None on the base so the attribute access is checked.

the URL check is field_validator on each subclass

Brandon-Shippy marked this pull request as ready for review September 16, 2026 17:37

Brandon-Shippy requested review from alexluck-sift, solidiquis and wei-qlu and removed request for wei-qlu September 16, 2026 17:37

alexluck-sift reviewed Sep 16, 2026

View reviewed changes

Brandon-Shippy requested a review from alexluck-sift September 17, 2026 20:23

wei-qlu requested changes Sep 20, 2026

View reviewed changes

Brandon-Shippy added 4 commits September 21, 2026 08:55

python(feature): add webhooks resource and webhook rule actions

eb9fec1

update wording

556f856

fix ci tests

4a55e0c

pyright model

1d4e18b

Brandon-Shippy force-pushed the python/webhooks-resource branch from 2baa0a6 to cecc9b0 Compare September 21, 2026 16:00

address review: keep RuleAction.annotation, drop Ref alias, accept As…

a6ddb67

…set in asset_ids

Brandon-Shippy force-pushed the python/webhooks-resource branch from cecc9b0 to a6ddb67 Compare September 21, 2026 16:04

alexluck-sift reviewed Sep 21, 2026

View reviewed changes

Brandon-Shippy added 3 commits September 22, 2026 18:12

python: address changes

38c50f7

fix ci, mkdocstrings err

4733395

python: update WebhookTest

dc8d34e

Brandon-Shippy requested review from alexluck-sift and wei-qlu September 23, 2026 03:40

		return cls(int(val))


		class RuleAction(BaseType[RuleActionProto, "RuleAction"]):


		#### Webhooks API

		New `client.webhooks` resource, and `RuleAction.for_webhook(...)` to attach a webhook to a rule.

		return cls(name=proto.name, value=proto.value)


		class WebhookTestResult(BaseModel):

Conversation

Brandon-Shippy commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Validation

Uh oh!

github-actions Bot commented Sep 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wei-qlu Sep 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexluck-sift left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Brandon-Shippy commented Sep 14, 2026 •

edited

Loading

github-actions Bot commented Sep 14, 2026 •

edited

Loading

wei-qlu Sep 20, 2026 •

edited

Loading