A project milestone can be a useful signal for a thank-you, but it is not permission to send one. A reliable design translates a verified Linear event into a reviewable request, checks the recipient and budget under the organization's rules, obtains a human decision, and reconciles the final outcome. This guide is an architecture and test plan for a team building its own adapter. It does not claim that Linear and Giftpack have a native integration or that an issue status alone establishes recipient consent.
The sequence matters: an event says something changed in a project; an approved gift request says a responsible person has decided what may happen next. Keep those records separate. The examples below are hypothetical and must be adapted to the workspace's actual Linear model, the company's gift policy, and the chosen fulfillment path before production use.
Define the milestone as an auditable business decision
Begin with a milestone that the organization can recognize without interpreting a free-text comment. A project update, a project state change, or an issue transition might be a candidate signal, but the product owner must decide which event and field combination actually represents completion in that workspace. The Linear API and webhook overview identifies project and issue change events; it does not make any particular change an approved gifting instruction. Record the workspace, project, team, milestone identifier, expected prior state, accepted new state, and the source of the business rule. If a team uses a custom issue label as the milestone, document the exact label ID and who may apply it.
The decision should answer six questions before an endpoint is configured. Who is eligible, and does the program cover employees, external contributors, or customers? Who may approve the value and recipient category? Which cost center pays? Is the gift optional, and how will the recipient receive a transparent invitation or decline route? What evidence closes the work when a package is delivered, declined, returned, or never claimed? Finally, which system is authoritative for each answer? Linear is a project-work record, not necessarily the source of legal name, address, country restrictions, or employment policy. Do not copy those details into an issue merely to make the automation easier.
Write a one-page policy card owned by product operations, finance, privacy, and the program sponsor. It should name the intended occasion, permitted recipient classes, monetary ceiling, restricted counterparties, geographic exclusions, sender, expiration period, and escalation owner. A milestone outside that card should produce a rejected or manual-review record, not a guessed default. In a regulated or public-sector relationship, the employer and legal team decide whether any gift is appropriate; the adapter must be able to stop.
Choose the event and protect the intake boundary
Linear's webhook documentation describes HTTP POST delivery for data-change events and an event envelope with action, type, data, updatedFrom, createdAt, and webhook identifiers. The current documentation lists projects and project updates among supported models. Configure only the workspace/team and resource types needed for the program, with an administrator or authorized application setting up the webhook. Do not turn on every team just because the endpoint can accept it. Store the signing secret in a server-side secret manager; access to that secret and to the reviewer queue should be distinct.
At the public HTTPS consumer, retain the raw request body until it has been authenticated. Linear documents a Linear-Signature HMAC-SHA256 over the raw bytes and a webhookTimestamp for replay protection. Compare signatures in constant time, reject a stale timestamp under the team's chosen tolerance, validate the organization and webhook subscription, and bound payload size before parsing business fields. The example in Linear's documentation uses a one-minute timestamp guard; a deployment should test clock synchronization and legitimate delivery delays before fixing its production window. A bad signature is a security event, never a request for a gift. A valid signature says the event came through the configured channel; it does not prove the milestone is true, eligible, or approved.
Return a successful response only after the authenticated event and its durable intake record have been committed. Linear documents a public HTTPS endpoint and a 200 response, with retries after failed deliveries. A slow downstream gift system should not keep the webhook request open. Enqueue the verified event and answer the webhook, then run policy evaluation asynchronously. If the durable write fails, return an error and allow the documented retry behavior. Monitor subscription disablement after repeated delivery failure; a quiet dashboard is not proof that no milestone occurred.
The intake record can contain a transport key such as Linear-Delivery, event time, workspace and project IDs, a hash of the raw payload, signature-verification result, and processing state. Encrypt it and restrict access. Keep gift recipient details out of this transport log. A separate business key ties a confirmed milestone to one entitlement; the transport key alone cannot prevent two distinct but equivalent project updates from creating two gifts.
Map one milestone to one reviewed entitlement
Define a stable business key from the workspace, project, milestone definition, program version, and intended recipient role. This is a design key owned by the integration, not a Linear-provided universal gift ID. The database should enforce uniqueness for that key while preserving every delivery attempt in an append-only event history. For example, a second update to the same completed project may create another Linear-Delivery value. It should attach to the existing pending or closed entitlement, not open a second spend. If the milestone is genuinely reset and completed again, the business owner must decide whether that is a new entitlement and version the policy explicitly.
The state machine is deliberately conservative. Observed means a verified event is stored. Candidate means the workspace/project and transition match the registered rule. Needs review means eligibility and a proposed recipient have been checked without revealing unnecessary personal data to the project team. Approved records the named approver, policy version, amount ceiling, time, and immutable approval reference. Submitted means a request was handed to the chosen execution path. In progress, delivered, declined, failed, and closed are reconciled from that execution path and support records. A cancellation or policy revocation before submission must stop the transition. A changed amount, recipient, or destination after approval requires a fresh decision.
| Gate | Input and owner | Evidence to retain | Failure action |
|---|---|---|---|
| Intake | Signed Linear event; integration owner | Delivery ID, verified time, project ID, raw-body hash | Reject unsigned or stale request |
| Milestone | Registered transition; product owner | Rule version, before/after state, business key | Hold ambiguous change |
| Eligibility | Approved program roster; program and privacy owners | Recipient reference, restrictions, decision time | Suppress ineligible recipient |
| Approval | Value, purpose and cost center; finance or delegated approver | Named approval, ceiling, expiry, policy version | No submission without approval |
| Execution | Approved invitation or order; operations owner | External request/reference, response, lifecycle state | Reconcile unknown result before retry |
The table is a control design, not a claim that either vendor supplies these custom states. A small team can implement the queue in a ticketing or internal form system, provided it has unique keys, access controls, durable evidence, and a responsible human. A manual handoff may be preferable when event volume is low or API access is unavailable. It is slower, but its approval trail can be clearer than an untested automatic path. Compare the cost of operating the adapter, monitoring incidents, and reviewing exceptions with the benefit of reduced manual intake; do not assume automation always wins.
Keep recipient data outside the project event
The webhook should carry a project signal and a reference to a potential recipient, not a home address or broad employee profile. Resolve identity from an approved system only after a candidate passes the business rule. Use the minimum fields needed for policy review and invitation. If the recipient can choose an item and provide delivery details directly in an approved fulfillment flow, the project board need not contain the address at all. Document the legal basis, notice, retention, regional access, and support path with the organization's privacy owner. The corporate gifting data-governance guide gives a broader operating checklist, but local law and company policy still control.
Define who may see each field. A project manager may see the milestone and whether a review is pending. A gift program operator may see the recipient reference and approved category. A fulfillment operator may see details necessary to deliver. Finance may see cost center and approved value, not the message body or address. An analyst may see de-identified outcomes. Log accesses to sensitive records and set deletion periods separately for webhook diagnostics, approval evidence, and delivery evidence. A retention period that works for a transient technical log may be too short for an audit record or too long for an address.
An external contributor may be a supplier employee, open-source maintainer, customer contact, or government official. Those are different risk classes. Do not infer consent from participation in a project or from a public profile. The program owner should confirm a permitted invitation channel, employer gift rules, sanctions and anti-bribery screening where applicable, and whether the value is a gift, reimbursement, honorarium, or compensation. If that question cannot be answered, the adapter stops at review. Giftpack or any fulfillment service cannot make those employer, legal, tax, or privacy decisions for the company.
Select an execution path without inventing a connector
After approval, operations can manually create the approved gift invitation, or a separately authorized backend can use the Giftpack API Guides to choose the appropriate resource family. The official guide distinguishes campaign/giftee flows for recipient-choice recognition from direct marketplace order/receiver flows. It describes server-side credentials, asynchronous fulfillment and delivery events, and a separate API reference for exact schemas. Verify the workspace's feature access, endpoint permissions, request fields, error contract, and current event catalogue in its own environment before implementing. This article does not assert a built-in Linear–Giftpack connector or that a particular create call is available to every account.
The adapter should record a stable external business reference and its own request tracking ID before a downstream write. If the request times out, look up the original reference and external resource status through supported read operations before considering a retry. An HTTP success may mean the request was accepted, not that an invitation was redeemed or a shipment delivered. Giftpack's guide warns against treating those stages as interchangeable. Never infer fulfillment from the initial response. Keep production API keys out of Linear comments, browser code, screenshots, and logs; use environment-specific server secrets and a service account with the minimum authorized scope.
This is also a fair fit comparison. A team with infrequent milestones and strict discretionary review may prefer a human-operated form and an approved supplier. A team with a high volume of repeatable recognition events and a verified Giftpack account may benefit from its recipient-choice and fulfillment lifecycle, after confirming terms and coverage. A team already committed to another vendor should compare integration access, event evidence, local delivery coverage, recipient choice, cost, failure recovery, and support under the same criteria. No invented score or default rank is warranted. The Giftpack approval workflow guide explains the organization-side controls that remain necessary regardless of provider.
Hypothetical decision one: a product beta milestone
Suppose a product operations team wants to thank external beta contributors after a release candidate is accepted. The Linear project receives a completion update, but the update can be edited and a project can move backward. The team registers the exact project and milestone rule. The program sponsor limits the gift to contributors who completed a documented review, prohibits gifts to public officials or restricted customer contacts without special review, and chooses a recipient-choice invitation rather than shipping a preselected item. Finance approves a per-person ceiling and a program total. A community manager owns recipient eligibility; the privacy owner approves the contact route; an operations approver makes the final decision.
The adapter receives a verified project event and creates one candidate per eligible contributor reference. It does not populate recipients from every Linear commenter. Each candidate carries the same project milestone version but its own recipient business key. The manager checks contribution evidence outside the gifting queue; the approver can reject, defer, or approve each one. A declined invitation closes without fulfillment. A returned shipment reopens support but does not automatically issue another gift. The acceptance test sends two equivalent webhook deliveries, then a new project update with a different transport ID but the same business milestone. The expected result is one candidate per approved contributor and one execution reference per approved candidate, with both deliveries retained as evidence.
The alternative is a manual spreadsheet review and invitation run. It avoids a webhook service and may be adequate for a dozen contributors, but someone must own dedupe, policy changes, and the audit trail. The automatic path becomes worth testing only when the same controlled decision recurs often enough. Failure recovery is explicit: if the recipient mapping is wrong, quarantine the candidate, correct the approved roster, and rerun evaluation without reusing a previous approval for a different person. If the downstream submission result is unknown, freeze that business key until the original resource is reconciled. The case is illustrative, not a customer result or a claim about conversion.
Hypothetical decision two: a cross-border rollout checkpoint
Suppose an enterprise rollout project in Linear reaches a signed-off regional launch milestone. The intended recipients are internal implementation leads in several countries. The organization wants to offer a small completion gift, but country rules, payroll treatment, shipping availability, and addresses differ. The project owner confirms the signed-off evidence; HR and legal define which employee groups may receive a gift; finance approves value in a documented currency and cost center; a regional operations lead checks whether a recipient-choice or local sourcing path fits. The rule is not “all assignees of the project.” Assignment may reflect temporary work, and the milestone can be marked complete before local acceptance.
The first event creates a single rollout review record. The approver sees country-level counts and exceptions, not addresses. Once the roster and policy are approved, the execution service creates separate recipient entitlements keyed by region, employee reference and milestone version. One region is held because local policy requires an additional decision. Another has a valid approved invitation but no shipping coverage for the desired item; operations offers an approved local alternative or declines the request. The adapter cannot silently substitute an item with a different value or cultural meaning. A later correction to the Linear milestone changes the review state, but does not erase a fulfilled gift or rewrite approval history.
Test an out-of-order project update, a repeated webhook, a revoked approval, a rate-limit response, and an unknown downstream timeout. The evidence should show no duplicate spend, no unauthorized country, a named disposition for every exception, and a finance reconciliation between approved ceiling, accepted request, actual charge, and reversal or credit. If the audit cannot explain a gap, stop future submissions for that program and reconcile the original IDs. The alternative is a scheduled manual regional review; it trades immediacy for a simpler control surface. Neither path proves that a gift improved retention or team morale. For measurement, define a separate outcome and comparison design rather than attributing a business result to the webhook.
Replay, monitor and reconcile before expanding
Build a replay runbook before launch. It should state the operator, prerequisites, source event ID, business key, expected current state, and read-only checks. A replay may re-evaluate an event against the same policy version, but must not produce a new entitlement merely because the transport ID changed. A policy change creates a new proposed decision and requires explicit reapproval when value, eligibility, or destination differs. Preserve a durable ledger of event received, rule evaluated, reviewer decision, external request attempted, external response, subsequent lifecycle event, support action, and finance closure. Separate the event ledger from recipient data under access and retention controls.
Monitor rejected signatures, old timestamps, delivery failures, disabled subscriptions, queue backlog, duplicate-key suppressions, approval age, downstream errors, and unreconciled submissions. Linear's rate-limiting guidance applies to GraphQL calls used for enrichment or backfill; a webhook push itself is not a license to hammer the API. Use pagination and a bounded backfill after outages, honor current response headers, and design a manual hold if verification reads are unavailable. Do not attempt to reconstruct an order from a dashboard screenshot when the external resource's state is unknown.
Run acceptance tests with synthetic data and no live recipients. Test a valid milestone, a non-matching project, a duplicate delivery, two different deliveries for the same milestone, a changed recipient, revoked approval, clock skew, tampered signature, delayed webhook, queue crash after durable write, downstream timeout, rate limit, failed fulfillment, and return. For each test, record the expected state, actual state, business key, external reference, and operator signoff. Then pilot a narrowly scoped approved cohort with a kill switch and a daily reconciliation owner. The corporate gifting measurement framework helps distinguish workflow completion from a separate outcome study.
What if a milestone is reversed after approval?
If nothing was submitted, pause or cancel under the policy and retain the decision history. If an invitation was already sent, consult the recipient experience and the authorized cancellation process; do not delete the original record. If a gift is fulfilled, reconcile actual cost and support disposition rather than issuing an automatic compensating gift. A source-system reversal is new evidence, not an instruction to erase downstream history.
A useful conclusion is a safe decision path
A Linear event can make milestone recognition timely, but the successful handoff is a traceable decision, not an automatic parcel. The engineering team owns verification and dedupe; the program owner owns eligibility; finance and policy owners own approval; operations owns fulfillment exceptions; and an independent reconciler closes the money and lifecycle records. Ship the smallest version that can show one real approved request without duplicating a gift under retries, reversals, or an unknown result. Expand only after the team can explain every exception in the pilot.
For an organization that has approved its program and verified access, Giftpack can be considered as a recipient-choice and global fulfillment execution path. The organization still decides whether to give, who qualifies, what may be spent, what data may be shared, and how its results are judged.