Support webhook integrations

[Json-Andriopoulos]

Describe changes

Introduces a new project-level component called webhook-integrations. Users can use the feature to create an integration point within ZenMl for events on extternal platforms (like Github).

The PR focuses on getting CRUD functionality in place (CLI, SDK, Rest, SQL). Integration with trigger code is out of scope and will be a follow-up branch.

Pre-requisites

Please ensure you have done the following:

• I have read the CONTRIBUTING.md document.
• I have added tests to cover my changes.
• I have based my new branch on develop and the open PR is targeting develop. If your branch wasn't based on develop read Contribution guide on rebasing branch to develop.
• IMPORTANT: I made sure that my changes are reflected properly in the following resources:
  • ZenML Docs
  • Dashboard: Needs to be communicated to the frontend team.
  • Templates: Might need adjustments (that are not reflected in the template tests) in case of non-breaking changes and deprecations.
  • Projects: Depending on the version dependencies, different projects might get affected.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Other (add details above)

[htahir1]

@Json-Andriopoulos nice work on this - one request while the adapter design is still soft.

We have concrete customer demand (can't name names here) for exactly this flow with Firecrawl's monitoring webhooks: a monitor detects a page change, posts a monitor.page event, and that should trigger a pipeline snapshot. I just built an example around it on example/firecrawl-web-monitor (#5065) - right now it works around the missing trigger integration by pulling checks via the Firecrawl API, but webhook triggers are the architecture we actually want to sell there.

Two things in the current BaseWebhookAdapter would need overrides for Firecrawl, and they're probably representative of a lot of non-GitHub providers:

1. Auth: Firecrawl doesn't sign payloads with HMAC - it sends whatever custom headers you configure on the monitor (typically a shared bearer token). So authenticate() assuming an HMAC signature header shouldn't be baked into the base contract, just into the GitHub adapter.
2. Event type location: parse() requires the event type in a request header (self.event_header), but Firecrawl puts it in the JSON body ("type": "monitor.page"). An adapter should be able to derive event_type from the parsed payload.

Both are cheap to generalize now and annoying to retrofit once adapters exist downstream. Happy to contribute a FirecrawlWebhookAdapter as the first non-GitHub adapter once the trigger follow-up branch is ready - the example gives us a live end-to-end test bed for it.

[github-actions]

Documentation Link Check Results

✅ Absolute links check passed
✅ Relative links check passed
_{Last checked: 2026-07-16 11:32:35 UTC}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 74918aef-b14b-420f-b81f-f0d2ed6b5b16

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/webhook-integrations

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[schustmi]

If the commit fails, shouldn't we delete the potentially newly created secret, similar to the create method?

[Json-Andriopoulos]

Hmm, valid but making this operation atomic is more complex that is sounds. Current code separate secret & metadata updates which is the simplest solution imo.

[schustmi]

Not sure if this is going to hurt with a potentially large amount of events coming in (imagine a GH webhook for lots of events in a huge organization). Every authentication check would now require one extra secret call that could be avoided by not allowing referencing existing secrets (or allow referencing it on creation, but don't point to it but instead just duplicate the value).

Would also reduce some of the complexity in the rotate handling. WDYT?

[Json-Andriopoulos]

Hmm, duplicating the value won't work that easily. We would need to keep it updated when it is rotated. I like referencing the secret as UX but you are right unless a reliable cacheing layer is available we should avoid it for now.

[schustmi]

What I meant was essentially: We just copy it from their original secret, but from that point on it's completely disconnected. As in, rotating the original secret wouldn't work, they would need to rotate it via the webhook rotate request. But I guess that's also confusing.

In the current implementation though, the user wouldn't even know what secret they've connected to the webhook, which is also not ideal IMO.

[Json-Andriopoulos]

So, current code optimizes a bit the Db and Store I/O by reducing operations to a minimum:

1. We drop support for more expensive secret reference
2. We make webhook integration resolution at the intake endpoint super light
3. We make stats update 1-pass (converted nested stats to flat table).