Captainhook Laravel Package

Product Decisions This Supports

• Build vs. buy vs. adopt for outbound webhooks. This package is not a platform; it's a reference implementation of one pattern — an event-to-subscriber-URL map, a model trait, and a queued HTTP POST. That makes the "do we even need this?" question cheap to answer. A customer-visible v0 can sit in front of design partners in days, and adoption data — not opinion — drives what comes next.

• Demand validation for integrations. If Sales and Support keep hearing "can we get order/invoice/user events pushed into our CRM, warehouse, Zapier, or n8n," ship a thin version behind a flag and instrument it. The metrics that decide the roadmap: how many accounts register an endpoint, which event types they subscribe to, and what percentage of deliveries succeed. That data justifies — or kills — the real investment.

• Event taxonomy as a public contract. This is the product work the package does not do, and it's the work that's expensive to get wrong later. Whether created alone, or also updated/deleted/domain events, become customer-facing API is a permanent decision. Prototyping on a throwaway implementation forces that conversation now, while it's cheap.

• Pricing and packaging. Webhooks are frequently a paid-tier or "Enterprise integrations" lever. A cheap pilot tells you whether customers value event push enough to pay for reliability (retries, replay, delivery logs) versus merely wanting "it exists."

• Roadmap sequencing for platform work. A durable webhook system — signing, retries with backoff, dead-lettering, replay, per-endpoint filtering, rate limits, self-service endpoint UI — is weeks of engineering, and the endpoint UI is usually the bulk of it. The pilot gives a defensible order: prove demand → invest in delivery guarantees → invest in developer self-service.

• Prototype and partnership use cases. Internal tools, design-partner betas, fan-out to a handful of first-party endpoints, workflow triggers where delivery is not yet contractual. Good enough for a beta; not for a customer SLA.

• Architecture reference for an in-house build. Even if the dependency never ships, the source is a readable template for "model event → queued job → signed HTTP callback," and a legitimate input to an internal estimate.

• One decision that must come first: don't scope on unverified inputs. The supplied material contradicts itself — the repo tagline says "add webhooks to your Laravel app," while the package description describes a Git hook manager installing scripts into .git/hooks. Those are different products with different users and different risk profiles. The first PM action is to have an engineer confirm which one is in the repo (composer.json, src/, README) before a single line of a roadmap depends on it. An hour of verification beats a sprint spent on the wrong problem.

When to Consider This Package

Worth a time-boxed spike when:

• You need to validate webhook demand in days, not sprints, and the cost of being wrong is roughly one engineer-week.
• Your event surface is small (1–5 events) and subscribers are trusted first-party or design-partner endpoints.
• Reliability is explicitly not contractual yet — no SLA, no replay, no audit requirement.
• You're on, or can isolate to, the Laravel 5.x era this targets, and you're prepared to vendor or fork it as your own code from day one.

Reject it, or look elsewhere, when:

• You're on Laravel 8+/PHP 8. Last release was December 2016, 334 stars, zero Packagist dependents — treat it as abandoned. Expect Composer constraint conflicts, HTTP client drift, and container/event-dispatcher incompatibilities. Budget a rewrite, not an upgrade.
• You need production delivery guarantees: retries with backoff, dead-lettering, auto-disable on repeated failure, delivery logs and observability, manual replay, per-endpoint event filtering, rate limiting, idempotency keys.
• Security and compliance are in scope. Customer-supplied URLs mean SSRF exposure (block link-local and private ranges); unsigned payloads mean spoofing. You need versioned HMAC secrets, rotation, TLS enforcement, and a documented payload schema — confirm each exists before promising any of it to a customer.
• You need to receive third-party webhooks. This is an outbound-only pattern; inbound ingestion is a different problem (verification, replay protection, ordering) and this does nothing for it.
• The Git-hooks reading turns out to be correct instead. Then the value proposition changes entirely: it's developer-experience tooling — versioned hook config, installable per clone, mirrored in CI — judged against husky-style alternatives, not against a webhook platform. Either way, an unmaintained dependency executing shell commands built from config needs a security read before it goes near anything user-influenced.
• A one-off is the real need. If a single integration is in play, a queued job in your own codebase is less code than adopting, vendoring, and owning a package.

How to Pitch It (Stakeholders)

To executives: We can test whether customers actually want event-driven integrations for roughly one engineer-week instead of a multi-week platform build. Webhooks are a common paid-tier and enterprise-integration lever, so the pilot answers a pricing question as well as a product one. The catch, stated plainly: the library itself is unmaintained (last release 2016, no dependents) and must be treated as a prototype or a reference design, not a foundation we build a customer SLA on. We are buying information, not infrastructure. The decision this unlocks is whether to fund a real, durable webhook platform — with signing, retries, replay, and self-service — and the pilot data will tell us.

To engineering: Treat this as ~200 lines of readable code you'll own, not a dependency you'll maintain. Fork or vendor it, pin it, and expect to patch it — assume no security fixes and no upstream triage. Use it to get the shape right (model event → queued job → HTTP POST → delivery record), then replace it if the product decision is "ship for real." Two non-negotiables if we go ahead: never test against the sync queue driver, and log every delivery attempt — without a delivery log we cannot answer a customer's "we didn't get the event" ticket. Also, before any of this, resolve the documentation conflict about what the package actually is; the README and the description disagree, and the source is the only trustworthy source here.