Designing a Greenhouse Recruiting corporate gifting integration is less about connecting two products than about defining exactly when a recruiting event becomes an approved recipient experience. The safest design treats Greenhouse as the recruiting source of record, an internal service as the policy and reliability boundary, and the gifting platform as an execution layer after eligibility, privacy, budget, and cancellation checks pass.
A recruiting event becomes a gift only after identity, policy, timing, and cancellation controls agree.
Define the recruiting moment before choosing an event
A useful architecture starts with an occasion statement, not a webhook name. Write one sentence for each permitted experience: who may receive it, which recruiting milestone proves eligibility, which approver owns the policy, what value is allowed, when dispatch may occur, and which later state must cancel it. Separate interview appreciation, candidate-stage programs, accepted-offer welcome, and employee onboarding because they have different legal bases, budgets, data owners, and reversal rules.
Do not enable a rejected-candidate gift by default. A rejection event can carry heightened sensitivity, and a well-meant item may feel transactional or create inconsistent treatment. If a specific market or program wants post-process appreciation, require a documented purpose, an opt-out path, consistent criteria, and privacy review. A recruiting operator should never be able to turn a broad status event into an unreviewed global campaign.
Use a decision record with six fields: occasion, eligible population, authoritative event, required approval, dispatch delay, and cancellation events. Add a seventh field for the employee-system handoff. Once an accepted candidate becomes an employee, onboarding systems usually become the better owner of continuing recognition. The recruiting workflow should close its case rather than create a second employee master.
| Moment | Possible evidence | Default action | Required safeguard |
|---|---|---|---|
| Interview thank-you | Configured stage change or completed interview workflow | Create a reviewable invitation | Regional policy, value cap, and opt-out |
| Candidate-stage program | Entry to a narrowly defined stage | Reserve budget; do not dispatch immediately | Consistent eligibility and duplicate suppression |
| Accepted-offer welcome | Approved offer followed by accepted status | Queue with a cooling-off delay | Cancel on later offer or application change |
| Employee onboarding | Verified worker record in the employee system | Hand off to the employee program | No parallel recruiting-owned profile |
Choose Greenhouse evidence with explicit semantics
The official Greenhouse Recruiting Webhooks documentation describes JSON events delivered by HTTPS and includes a Greenhouse-Event-ID for each delivery. Candidate stage changes use the candidate_stage_change action. Offer events distinguish created, approved, updated, and deleted activity, while offer status can move through created, accepted, rejected, and deprecated states. These facts are useful signals, but no individual event should be treated as a complete business decision.
For an accepted-offer program, define the authoritative combination. One defensible rule is: application remains active, the current offer is approved, the offer status is accepted, the program and country are eligible, and the dispatch delay has elapsed without a superseding event. If the integration sees an offer update before an approval event, or an older payload after a newer state, it stores the event but recomputes eligibility from the latest known aggregate. Processing order must not become business truth.
The official Greenhouse Harvest API documentation can support confirmation or reconciliation. It documents candidate, application, job-stage, and offer resources; Basic authentication over HTTPS; per-endpoint permissions; pagination; rate-limit headers; and common 401, 403, 404, 422, 429, and 500 responses. Use Harvest as a bounded read path when a webhook lacks required context or a reconciliation job needs current state. Do not poll every candidate merely because the API exists.
Document information gaps. Greenhouse event names and payload fields may evolve, an organization may not have every endpoint permission, and a configured stage has local meaning. Record the event schema version observed in a test tenant, the exact endpoint permission granted, the stage and offer identifiers approved by recruiting operations, and the date each assumption was last verified. This guide verified the two official Greenhouse documents on September 24, 2026.
Minimize candidate data and separate identifiers from delivery details
Start with a field map that explains why every attribute crosses the boundary. A webhook receiver commonly needs the event identifier, event time, organization or tenant, candidate identifier, application identifier, job or program identifier, relevant stage or offer state, and a pointer to policy context. It rarely needs a résumé, interview notes, diversity data, compensation, or the full candidate object. Excluding a field is a design decision, not a later cleanup task.
Treat an email address, phone number, and postal address as delivery data, not as routing convenience. Where the experience permits recipient choice, create an approved invitation using a limited contact channel and let the recipient provide or confirm fulfillment details directly. If the business requires a physical item without recipient input, obtain a documented purpose, validate the allowed source, limit access, define retention, and separate the address vault from the event ledger.
Greenhouse notes that external URLs in Harvest responses are valid for seven days and that attachment URLs are temporary. If an approved workflow truly needs an attachment, download it immediately into an authorized store and apply its own retention controls; do not save a signed URL and assume it is durable. In most gifting flows, attachments are unnecessary, so the safer mapping excludes them entirely.
| Data class | Preferred treatment | Retention trigger | Owner |
|---|---|---|---|
| Event and entity identifiers | Store in the integration ledger | Audit and reconciliation period | Integration owner |
| Eligibility state | Store normalized state and source time | Program evidence period | Recruiting operations |
| Contact detail | Tokenize or transfer only after approval | Invitation expiry or fulfillment close | Privacy and program operations |
| Address | Prefer recipient-provided collection | Delivery plus approved exception window | Fulfillment operator |
| Résumé and interview notes | Do not ingest | Not applicable | Greenhouse only |
Privacy review should also settle notice, lawful basis, cross-border handling, deletion, access requests, opt-out, and incident response. The integration can enforce the approved result, but it cannot decide those questions for the organization.
Authenticate narrowly and verify every webhook
Create a dedicated Greenhouse credential for the integration. The Harvest documentation says endpoint access is selectable, although access within an endpoint is all or nothing. Grant only the endpoints needed for confirmation and reconciliation, keep the secret in an approved secret manager, prohibit it from logs and tickets, and define a rotation procedure before production. A 401 should trigger credential validation; a 403 should trigger permission or request-method review. Neither error should cause an automatic broadening of access.
For webhooks, preserve the exact raw request body before parsing it. Greenhouse documents an HMAC SHA-256 signature in the Signature header and emphasizes signing the exact body, including Unicode escaping. Compute the HMAC with the configured secret, compare in constant time, reject mismatches, and record a safe reason code. Do not log the secret, full candidate payload, or signature material.
Respond quickly after durable intake. Signature verification, schema checks, and a transactional insert should happen on the request path; policy evaluation, API enrichment, and gift preparation belong in a queue. If the endpoint times out after processing but before returning a success, Greenhouse may retry. Durable intake plus idempotency makes that retry safe.
{
"event_id": "synthetic-event-7f3a",
"action": "candidate_stage_change",
"occurred_at": "2026-09-24T14:05:00Z",
"candidate_id": "synthetic-candidate-1042",
"application_id": "synthetic-application-8801",
"job_id": "synthetic-job-72",
"from_stage": "screen",
"to_stage": "interview-complete"
}
This payload is illustrative and contains no real candidate data. Production code must validate the actual documented schema and the organization’s configured stage identifiers.
Make idempotency and state precedence first-class controls
Use the Greenhouse event identifier as the intake idempotency key, but do not stop there. A repeated delivery of the same event should return the stored intake result. Two different events can still describe the same business occasion, so create a second key such as tenant, candidate, application, program, and occasion version. Enforce a unique constraint at the gift-intent layer. This prevents an offer update and a stage change from creating two welcome gifts for one decision.
Maintain an event ledger and a derived intent record. The ledger is append-only and records event identifier, source timestamp, receive time, schema version, signature result, normalized references, and processing result. The intent record carries the latest eligibility decision, approval, budget reservation, contact-token reference, scheduled dispatch time, provider reference, and cancellation state. Rebuilding the intent from the ledger should produce the same answer.
Define state precedence before launch. A cancelled, rejected, deleted, or unhired condition should outrank a prior eligible state until an authorized operator explicitly creates a new occasion. A dispatching state may require a best-effort cancellation and human review rather than a simple database change. A delivered state is historical and cannot be erased by pretending the request never happened. Every transition should have an owner and an allowed previous state.
Out-of-order handling needs source time and entity version, not just receive time. Store later events even when they are stale, mark them as superseded, and avoid destructive updates. If two events have ambiguous precedence, pause the intent and ask recruiting operations to resolve the current application or offer rather than guessing.
Put policy, budget, and timing between eligibility and execution
Eligibility should create a gift intent, not a gift. The policy service evaluates program, geography, occasion, recipient class, value, tax or legal flags, consent or opt-out, budget owner, and frequency limits. A budget service then reserves value against the correct program and cost center. Only an approved, funded intent may enter the dispatch queue.
Use delays intentionally. An interview thank-you may be released after a short validation window. An accepted-offer welcome should usually wait through a configured cooling-off period so that corrections, duplicate offers, or reversals can cancel cleanly. Store eligible_at and dispatch_not_before separately. The former explains why the intent exists; the latter controls execution.
Choose the retry boundary carefully. Network timeouts and 429 responses may be retried with exponential backoff, jitter, and a maximum age. Validation failures, policy denials, missing budget, and authentication failures should not be blind retries. They need a durable exception with a clear owner. Greenhouse documents rate-limit headers and a Retry-After value for 429 responses; honor them instead of sending faster retries.
Exception rules the runbook should make explicit
-
If the candidate opts out before dispatch, cancel the intent and delete unnecessary contact data.
-
If an offer is revoked during the delay, release the reservation and preserve the cancellation evidence.
-
If a downstream request times out with an unknown outcome, reconcile by the business idempotency key before sending again.
-
If a credential is rejected, stop enrichment, alert the integration owner, and do not expand permissions automatically.
-
If a temporary attachment URL expires, fetch a fresh authorized reference only when the field is still required; never substitute an unrelated file.
Worked case A: interview thank-you after a configured stage
Assume a recruiting team wants a modest interview thank-you in the United States, Japan, Taiwan, and South Korea. The program applies only after a candidate completes a specific interview stage, excludes agencies and internal transfers, allows the recipient to decline, and uses regional value caps. Recruiting operations owns eligibility; talent brand owns the message; privacy approves the contact flow; finance owns budget; and integration engineering owns delivery controls.
The stage-change webhook is verified and inserted under its event identifier. The worker maps the tenant’s configured stage ID to interview_complete, reads only the candidate and application identifiers needed for current-state confirmation, and checks that the application is active. It creates an occasion key for the candidate, application, program, and interview cycle. A second event for the same cycle finds the existing intent and appends evidence rather than creating another reservation.
The policy service selects the regional cap from the candidate’s approved program location, not from a free-text address. It checks the opt-out registry and reserves the amount to the recruiting cost center. The system creates an invitation after the validation delay; the candidate chooses whether to participate and provides delivery details through the approved path. Recruiters see a neutral status such as invited, declined, expired, or fulfilled, not the recipient’s address.
Test the case by replaying the same event, delivering the event after a later status, changing the stage back before release, exhausting the regional budget, and submitting an opt-out. Acceptance requires one intent, no gift on a stale state, no dispatch without budget, successful cancellation before release, and deletion or expiry of unnecessary contact data. A delivery result alone is not enough evidence.
Worked case B: accepted-offer welcome with a safe cancellation window
Assume an accepted offer may initiate a welcome invitation, but employee onboarding begins only after the HR system creates a worker record. Recruiting operations approves job families and countries; people operations owns the welcome experience; finance supplies the program budget; privacy approves the handoff; and the integration team owns state reconciliation.
An offer event arrives. The worker records it but does not trust one payload as final. It confirms that the offer is approved and accepted, the application is active, and no newer rejected, deleted, deprecated, or unhired condition exists. The policy service creates a welcome intent with a three-business-day dispatch delay. Budget is reserved, but contact data is not transferred to fulfillment yet.
Two days later, a corrected offer update arrives. Because the business key already exists, the worker updates evidence and recomputes the dispatch time only if the program rule allows it. If the offer is revoked before release, a higher-precedence cancellation closes the intent and releases budget. If revocation arrives while the downstream outcome is unknown, the operator first reconciles by idempotency key, then cancels or intercepts when supported. The system never creates a second welcome merely because a new offer version was generated.
After the employee system creates a verified worker, the recruiting case stores a handoff reference and closes. Future anniversary or onboarding recognition belongs to the employee program. Acceptance tests cover accepted then revoked, duplicate offer updates, an older update delivered last, a 429 during confirmation, a timeout during dispatch, and a worker record that arrives before the delay ends. Each test must prove the final intent state, reservation result, contact-data handling, audit trail, and operator action.
Design failure recovery around known outcomes
Retries are safe only when the system knows whether a prior step had an effect. Classify every operation as not attempted, definitely rejected, accepted with a reference, or outcome unknown. A timeout after sending is outcome unknown; retrying it under a new key risks duplication. Reconcile first with the same business key or provider reference.
| Failure | Machine response | Human owner | Release condition |
|---|---|---|---|
| Duplicate webhook | Return stored intake result | None unless payload conflicts | Existing event fingerprint matches |
| Out-of-order state | Store as superseded; recompute aggregate | Recruiting operations if ambiguous | Authoritative current state confirmed |
| 401 or 403 | Stop enrichment and alert | Integration and security | Credential or permission repaired and tested |
| 429 | Honor reset or retry-after; add jitter | Integration if backlog breaches target | Capacity restored within maximum age |
| Expired signed URL | Do not reuse it | Data owner if field remains necessary | Fresh authorized reference or field removed |
| Downstream timeout | Mark outcome unknown and reconcile | Program operations for unresolved cases | One provider result tied to the business key |
Quarantine malformed or unauthorized events without exposing their bodies in alerts. Put replay behind an operator role, require a reason, and reuse the original event and business keys. A dead-letter queue is not a resolution; each class needs an owner, service target, maximum retention, and an approved disposition.
Test the integration as a stateful system
Use a Greenhouse test environment or controlled test records that reflect production configuration without using real candidate data. Build fixtures for every approved event, ignored event, cancellation, duplicate, out-of-order sequence, invalid signature, schema change, permission failure, rate limit, and downstream unknown outcome. Synthetic identifiers should remain clearly synthetic in logs and screenshots.
The minimum release checklist is executable:
-
Occasion statements and exclusion rules are approved.
-
Event and field maps match the configured Greenhouse tenant.
-
Harvest permissions are limited to documented confirmation and reconciliation needs.
-
The webhook signature is verified against the exact raw body.
-
Event and business idempotency constraints pass replay tests.
-
Policy, budget, opt-out, delay, and cancellation paths pass.
-
Secret rotation succeeds without losing durable intake.
-
401, 403, 422, 429, 500, timeout, and expired-link responses have runbooks.
-
Reconciliation produces the same intent state from source evidence.
-
Rollback disables new dispatch while preserving intake and audit history.
Separate deployment from activation. Ship the receiver in observe-only mode, compare normalized events with recruiting operations, then enable intent creation without dispatch. Next enable a bounded pilot by country, job family, and value. Expand only after duplicate rate, queue age, cancellation latency, exception backlog, and reconciliation differences remain within approved limits.
Monitor decisions, not just requests
Technical uptime does not prove program correctness. Monitor valid and invalid signature counts, intake latency, duplicate deliveries, schema failures, queue age, enrichment calls, rate limits, intent decisions, reservations, dispatches, cancellations, unknown outcomes, and reconciliation mismatches. Segment operational metrics by tenant, program, event type, and region without exposing candidate identity in general dashboards.
Create a daily reconciliation from source events to gift intents and from approved intents to downstream results. Explain every gap: ignored by policy, waiting for delay, blocked by budget, cancelled by later state, expired, failed with an owner, or completed with a reference. Use weekly sampling to compare the stored current state with Greenhouse for active intents. The goal is reproducible decisions, not a superficially high success rate.
Alert on conditions that require action: signature failures above baseline, a sudden drop in expected events, queue age beyond the program window, repeated 401 or 403 responses, sustained 429 responses, cancellations waiting near dispatch, or multiple downstream results for one business key. Suppress alerts for known retries only when the underlying intent is safe.
Rollback should disable new dispatch first, keep signed event intake running when safe, and preserve reservations and evidence. Operators then reconcile open intents, cancel or complete them deliberately, rotate secrets if compromise is suspected, and document the activation criteria. Deleting the queue is never a rollback plan.
Keep ownership and evidence clear after launch
Recruiting operations owns event meaning and stage configuration. Privacy and legal own approved data use, notice, retention, and regional exceptions. Security owns credential storage and incident requirements. Finance owns value limits, budget, and reconciliation policy. People or talent brand owns recipient communication. Integration engineering owns validation, state, retries, observability, and technical rollback. The gifting operator owns approved execution and fulfillment exceptions.
Review the design whenever Greenhouse configuration changes, the webhook or API schema changes, a new country or occasion is added, a budget rule changes, an employee-system handoff changes, or incident evidence exposes an assumption. Record last-verified dates for official documentation and test the actual tenant; a generic documentation review cannot validate local stage meaning.
Preserve evidence in three layers: immutable source-event metadata, versioned policy decisions, and downstream execution references. Keep payload access restricted, store hashes or fingerprints when full content is unnecessary, and expire contact details on schedule. An auditor should be able to explain why an intent was created, approved, dispatched, cancelled, or ignored without seeing unrelated candidate data.
Launch a controlled recruiting-to-gifting workflow
The durable pattern is straightforward: define the occasion, verify the event, minimize fields, normalize state, deduplicate at event and business levels, confirm current eligibility, apply policy and budget, wait through the cancellation window, dispatch idempotently, and reconcile every outcome. The difficult work is not the HTTP request. It is making the decision reversible, observable, and fair when events repeat or arrive late.
Start with one occasion and one narrow population. Prove the replay, cancellation, rate-limit, unknown-outcome, secret-rotation, reconciliation, and rollback paths before expanding. Keep rejected-candidate gifting off unless a separately approved policy justifies it. Close the recruiting record when the employee system becomes authoritative.
Giftpack can serve as the gifting execution layer after your organization has made the recruiting, privacy, legal, budget, and employer decisions. Use the architecture review to validate what enters the execution boundary, how recipient choice is handled, and how fulfillment evidence returns to your ledger; do not treat the platform as a replacement for those governance owners.