# Zapier Trigger Webhook

## Objective

Push app events to a Zapier catch hook so users can continue the work elsewhere.

An outbound event delivery to a user-supplied Zapier hook URL, with event selection, signing, retries, and a delivery log.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Find the events the app already records internally — record created, status changed, payment received — and expose that existing list as the set a user can subscribe to. Do not invent a parallel event stream just for this integration.
2. Deliver every event through the app's existing background-job system, never inline in the request that caused it. A slow or unreachable hook must not delay the user's save.
3. Give each delivery a stable identifier that stays the same across every retry of that event, and put it in the payload so the receiving side can discard duplicates.
4. Store the destination URL encrypted at rest, show it only to workspace members who may edit the integration, and never render it or the signing secret into client-side code.
5. This brief owns the Zapier-facing configuration only. The delivery pipeline — queueing, signing, retry schedule, log, and auto-disable — is shared with the Make Scenario Trigger and n8n Workflow Trigger briefs; build it once and let all three destinations register against it.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A user can paste any URL, including one that resolves to a private address, a loopback interface, or a cloud metadata endpoint. Require HTTPS, resolve the host before connecting, and refuse targets inside internal network ranges so the integration cannot be used to reach services behind the app.
- A receiver has no way to know a payload genuinely came from the app unless it is signed. Sign every outgoing body with a per-integration secret, include a timestamp in the signed material so an old capture cannot be replayed, and document the scheme in the integration's settings screen.
- Retries and at-least-once delivery mean the same event will arrive more than once. Carry a stable event identifier so the receiving workflow can deduplicate rather than creating the same downstream record twice.
- Users need to confirm a hook works before trusting it with real activity. Provide a test delivery that is clearly flagged as a test in the payload and excluded from the production event history, so nobody wires a live workflow to sample data.
- An endpoint that has been deleted or has returned permanent failures for a long stretch will never succeed. Stop delivering after a defined run of permanent errors, mark the integration disabled, and tell the owner what happened and how to re-enable it.
- The receiving service will rate limit or time out under load. Back off with increasing delays plus jitter, cap the total retry window, and treat a timeout as retryable while treating an authorization rejection as permanent.
- Events fired in bulk — a large import, a batch status change — can produce thousands of deliveries at once. Bound how many are in flight per integration so one workspace cannot starve the queue for everyone else.
- A payload built from an internal record will leak whatever the record holds. Send a deliberately chosen field set, exclude secrets, internal notes, and other users' personal data, and version the payload shape so it can change without silently breaking live workflows.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Users select which event types are delivered, and nothing is delivered by default.
- [ ] Every delivery is queued and never blocks the user action that produced it.
- [ ] Outgoing payloads are signed, and each carries a stable identifier that survives retries.
- [ ] Destination URLs are validated as external HTTPS targets, and internal-network addresses are rejected.
- [ ] Test deliveries are distinguishable from production events and kept out of the production history.
- [ ] Repeated permanent failures disable the integration and notify its owner.
- [ ] A delivery log shows attempts, response status, and outcome for each event.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.