External Webhook Triggers — Integration

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Integration Points (from Spec)

​

API / Platform Contracts

​

Public Edge Function: fw-webhook-receiver

• Supabase URL: POST https://{project_ref}.supabase.co/functions/v1/fw-webhook-receiver/{org_slug}/{endpoint_slug}
• Path parsing: Full pathname includes /functions/v1/ prefix; extract org_slug and endpoint_slug as the two segments after fw-webhook-receiver (see process-inbound-webhook for a similar url.pathname.split('/') approach).
• Optional app gateway: Same path may be exposed as POST https://{app_host}/api/webhooks/{org_slug}/{endpoint_slug} via reverse proxy (implementation choice).
• JWT: verify_jwt: false — callers are not Supabase users; authentication is endpoint-specific (API key, HMAC, or bearer JWT from external IdP).
• Runtime credentials: Service role used only inside the function after successful endpoint auth, to call SECURITY DEFINER ingest RPC and write logs (see spec).
• PF-42 call pattern: Call pf_check_rate_limit with p_endpoint set to fw_webhook: plus the endpoint UUID — align with check-rate-limit (fail-open on DB error is PF-42 default; product may choose fail-closed for abuse-sensitive ingress in a follow-up).

​

SECURITY DEFINER RPC (planned)

• fw_webhook_ingest(...) (name illustrative): Validates resolved organization_id, endpoint active state, performs idempotency insert, creates workflow execution row, calls existing FW-46 enqueue path (pgmq.send / same contract as fw_process_domain_event worker flow). Invoked by edge with service role; not exposed to anon.
• fw_webhook_replay_log(...): Authenticated + fw_has_org_access; re-enqueues from stored encrypted payload metadata.

​

Idempotency

• Header X-Idempotency-Key optional. Dedup key: (endpoint_id, idempotency_key) when header present; else behavior unchanged from spec (payload hash window) for backward compatibility.

​

Security and Tenant Isolation

• No cross-core imports: all logic stays in FW + platform dependencies.
• Webhook payloads may contain PHI: store ciphertext only; restrict log body viewing to permission fw.webhooks.view (and replay to fw.webhooks.replay).
• Edge must not log raw bodies to console or external APM in production.
• RLS on fw_webhook_* tables uses fw_has_org_access(organization_id, auth.uid()) for authenticated app users; service role bypasses RLS for ingest path only inside controlled RPC.

​

Database: RLS policy patterns (Supabase / Postgres)

​

Authenticated app users (authenticated)

• Tenant scope: Every policy on org-scoped tables uses fw_has_org_access(organization_id, auth.uid()) (or, for child rows keyed by endpoint_id, a SECURITY DEFINER helper such as fw_webhook_endpoint_org_id(endpoint_id) so policies do not recurse — constitution §5.7).
• WITH CHECK on UPDATE: All FOR UPDATE policies must include WITH CHECK mirroring USING (constitution §5.2.9).

CREATE POLICY "fw_webhook_endpoints_select" ON fw_webhook_endpoints
  FOR SELECT TO authenticated
  USING (fw_has_org_access(organization_id, auth.uid()));

CREATE POLICY "fw_webhook_logs_select" ON fw_webhook_logs
  FOR SELECT TO authenticated
  USING (fw_has_org_access(organization_id, auth.uid()));

​

Ingest path (service role + RPC only)

• No broad anon INSERT on fw_webhook_logs or execution tables for ingress.
• The Edge Function uses the service role only to call SECURITY DEFINER RPCs (e.g. fw_webhook_ingest) that validate organization_id, endpoint state, idempotency, and then enqueue (FW-46). All writes from the public internet are funneled through that contract.

​

Database: required and recommended indexes

​

Webhook execution isolation (multi-tenant / PHI-safe)

1. Resolve tenant first: Map path org_slug → pf_organizations.slug → organization_id. Reject if unknown slug.
2. Resolve endpoint second: Load fw_webhook_endpoints by (organization_id, endpoint_slug) (and active / not suspended). Never select an endpoint by slug alone.
3. Bind workflow to org: The endpoint’s workflow_definition_id MUST reference a row whose organization_id matches the endpoint’s organization_id (enforce in RPC before enqueue; add a DB constraint or validate in fw_webhook_ingest if the schema allows cross-row checks).
4. Enqueue: Create / link fw_workflow_executions only for that definition and org; FW-53 and other limits apply after enqueue — no bypass.
5. Logs / PHI: Encrypted body in BYTEA only; structured edge logs contain no raw payload, headers with secrets redacted, and correlation ids only.

​

Monitoring, alerting, and PF-42 fail-open behavior

• DB error in rate limit check with { error, orgId, endpoint }
• Unexpected error in rate limit check with { error }

​

Alert thresholds (starting defaults — tune per environment)

• ≥ 10 pf42_* / pf42_rate_limit_* log lines per minute per project (or per org_slug if high-volume single-tenant).
• OR ≥ 5% of fw-webhook-receiver requests hitting the fail-open path over a 5-minute rolling window.

​

Channels and escalation

• Slack: #platform-alerts or #fw-webhooks for warning-level sustained rates.
• Pager / on-call (SEV-2+): Opsgenie/PagerDuty rotation shared by Platform SRE and FW module owner when fail-open volume indicates abuse or prolonged PF-42/DB outage.

​

Incident response playbook (short)

1. Triage: Confirm spike in Edge logs / Supabase metrics; segment by org_slug and endpoint_id.
2. Infra: Check Postgres availability, pf_check_rate_limit errors, and pf_rate_limits row presence for affected endpoints (FR-2.1a).
3. Mitigate: Enable FW_WEBHOOK_PF42_FAIL_CLOSED (see below) if fail-open is amplifying abuse or hiding enforcement; communicate to affected orgs if ingress is degraded.
4. Postmortem: For SEV-2+, document timeline, blast radius, and corrective actions within 72 hours.

​

Feature flag: fail-closed toggle

​

Event Contracts

​

Related Docs

• FW-59 Spec
• FW-59 CONTEXT — ingress edge decisions (PF-42 fail-open; points here for monitoring)
• FW-46 Durable Execution Worker
• FW-16 Event-Based Workflow Triggers
• PF-42 Rate Limiting
• PF-45 Feature Flags — FW_WEBHOOK_PF42_FAIL_CLOSED consumer pattern
• check-rate-limit Edge Function — reference log messages for fail-open
• CROSS_CORE_INTEGRATIONS.md