dust-webhook-source - SKILL.md Agent Skill

name: dust-webhook-source description: Implement a new built-in webhook source provider in `front`. Use when adding a webhook provider such as Linear, GitHub, or Fathom, including provider research, OAuth prerequisites, provider-specific types and client code, preset registration, UI components, and end-to-end testing.

Front Webhook Sources

Implement built-in webhook providers across two trees:

front/lib/triggers/built-in-webhooks/<provider>/ — UI-safe: presets, schemas, types, React components
front/lib/api/triggers/built-in-webhooks/<provider>/ — server-only: service + provider HTTP client

The boundary is load-bearing. Anything reached from the UI must never transitively import @app/lib/api/config, OAuthAPI, or other backend modules — putting server code under lib/api/ is how we enforce that. Do not re-introduce a webhookService field on the preset or instantiate the service from preset.ts: the leak that motivated the split will come right back.

The work spans provider research, OAuth prerequisites, typed remote metadata, a provider client, the remote webhook service, preset registration, services-map registration, and the setup/details UI.

Hard Prerequisites

Do not start implementation until both of these already exist:

front/lib/api/oauth/providers/<provider>.ts
core/src/oauth/providers/<provider>.rs

The provider must support the webhooks use case and have scopes that can manage webhooks.

If the provider only allows webhooks to be created manually in its UI, stop. It is not a fit for a built-in webhook source.

Research First

Before writing code, document these answers from the provider docs:

how to create a webhook programmatically
required auth method and OAuth scopes
request and response payloads for create and delete
available event types and sample payloads
how the incoming event type is identified: header or body field
what user-configurable metadata is required, such as team or repository selection
whether webhook signatures exist and how to verify them

This research determines the metadata types, client methods, event schemas, and UI.

Files To Touch

Minimal implementation:

front/types/triggers/webhooks.ts
front/types/triggers/webhooks_client_side.ts
front/lib/api/triggers/built-in-webhooks/services.ts (register the service instance)
front/lib/api/triggers/built-in-webhooks/<provider>/<provider>_client.ts (server-only)
front/lib/api/triggers/built-in-webhooks/<provider>/service.ts (server-only)
front/lib/triggers/built-in-webhooks/<provider>/types.ts
front/lib/triggers/built-in-webhooks/<provider>/preset.ts
front/lib/triggers/built-in-webhooks/<provider>/client_side.ts
front/lib/triggers/built-in-webhooks/<provider>/schemas/*
front/lib/triggers/built-in-webhooks/<provider>/components/*

Use existing providers as templates:

fathom for the simplest shape
linear for team-scoped webhook creation
github for repository-driven configuration

Workflow

1. Register the provider

In front/types/triggers/webhooks.ts:

add the provider to WEBHOOK_PROVIDERS
extend WebhookProviderServiceDataMap if the provider needs extra OAuth-fetched data
register the preset in WEBHOOK_PRESETS

In front/types/triggers/webhooks_client_side.ts:

import the provider client-side preset
register it in CLIENT_SIDE_WEBHOOK_PRESETS

In front/lib/api/triggers/built-in-webhooks/services.ts:

import the provider service class (from lib/api/..., not lib/...)
register an instance in WEBHOOK_SERVICES. This map is the server-only dispatch used by webhook create/delete/service-data endpoints. It must never be imported from UI code.

2. Define metadata and type guards

In types.ts, define:

create-time metadata entered by the user
persisted metadata that also includes provider webhook ids
runtime type guards for both
optional additional OAuth data such as teams or repositories

Always keep remote metadata serializable. No functions or class instances.

3. Implement the provider client

<provider>_client.ts lives under front/lib/api/triggers/built-in-webhooks/<provider>/ and should be a thin wrapper over the provider API. It is server-only; do not import it from UI code.

Typical methods:

createWebhook(...)
deleteWebhook(...)
getTeams() / getRepositories() / similar when setup requires selection data

Return typed results and map the provider response into the local metadata shape.

4. Implement the remote webhook service

In front/lib/api/triggers/built-in-webhooks/<provider>/service.ts, implement RemoteWebhookService<"<provider>">. This file is server-only — it will import OAuthAPI and @app/lib/api/config, which must never reach the client bundle.

Core responsibilities:

getServiceData(oauthToken) fetches setup data for the form
createWebhooks(...) validates metadata, creates provider-side webhooks, and returns updatedRemoteMetadata including webhook ids
deleteWebhooks(...) removes provider-side webhooks using the persisted ids

When multiple webhooks may be created, handle partial success explicitly and return user-facing errors without losing the successfully created ids.

5. Define event schemas

Create one schema file per event, or one per coherent event family, under schemas/.

Each event entry should provide:

the event name/value exposed in the UI
a JSON schema for the payload
an optional sample payload when it clarifies the shape

6. Build the presets

Split preset code correctly:

preset.ts exports a BaseWebhookPreset — data-only, UI-safe, worker-safe. Do not import React, icons, or the service here. The service is registered separately in WEBHOOK_SERVICES (see step 1).
client_side.ts exports a ClientSideWebhookPreset — it spreads the base preset and adds the provider icon plus React components.

Set on the base preset (preset.ts):

eventCheck to match how the provider exposes event type
the full list of supported events
optional webhookPageUrl

Set on the client-side preset (client_side.ts):

icon
the React components (detailsComponent, createFormComponent, and optionally oauthExtraConfigInput)

7. Build the UI components

Create:

CreateWebhook<Provider>Connection.tsx
WebhookSource<Provider>Details.tsx

The create form should:

rely on front/components/triggers/CreateWebhookSourceWithProviderForm.tsx for the OAuth connection flow via setupOAuthConnection(...)
treat connectionId as an input prop; do not recreate the OAuth flow inside the provider-specific form
fetch provider-specific setup data with useWebhookServiceData({ owner, connectionId, provider })
call onDataToCreateWebhookChange({ connectionId, remoteMetadata })
call onReadyToSubmitChange(true) only when configuration is complete

The details component should stay read-only and summarize the persisted remote metadata.

Common Gotchas

forgetting to register the data preset in WEBHOOK_PRESETS or the client-side preset in CLIENT_SIDE_WEBHOOK_PRESETS
forgetting to register the service in WEBHOOK_SERVICES
putting the service or provider client under lib/triggers/... instead of lib/api/triggers/... (leaks OAuthAPI and backend config into the client bundle)
importing React, icons, or the service from preset.ts (any of those turn BaseWebhookPreset into a client-only module and reintroduces the bundle leak)
putting the icon on the base preset rather than the client-side preset
storing non-serializable remote metadata
skipping type guards before using remoteMetadata
assuming a single webhook when the provider needs one per team or repository
ignoring partial success during multi-webhook creation
forgetting to make local webhook URLs public during manual testing

Testing

For local testing, expose the local app publicly and set DUST_WEBHOOKS_PUBLIC_URL.

Manual checklist:

complete the OAuth flow successfully
create the webhook source in the UI without errors
verify the webhook exists in the provider dashboard
trigger a real provider event and inspect local logs
confirm the incoming payload matches the registered schema and event detection logic
delete the source and verify the provider-side webhook is removed

References

front/lib/resources/webhook_source_resource.ts
front/types/triggers/remote_webhook_service.ts
front/types/triggers/webhooks_source_preset.ts