A recruiter changes a record in Greenhouse. Another system needs that change, but someone still copies it by hand. A webhook can start the handoff. The difficult part is deciding what the receiving workflow may do, how it handles repeated delivery and who notices when processing stops. Build those rules before connecting an AI agent.
This guide focuses on the event receiver and the recruiting task it starts. It does not treat webhook setup as permission to contact candidates, change a hiring decision or copy every field into another tool. Begin with one narrow task that a recruiter can inspect.
What a Greenhouse webhook actually sends
Greenhouse sends a JSON payload by POST to an HTTPS endpoint when a configured event occurs. Its documentation includes application creation, application updates, candidate deletion and candidate anonymization events. Choose the event that matches the work you need. Do not subscribe to everything just because the option exists.
Greenhouse includes a Greenhouse-Event-ID header with a unique ID associated with the delivery. Record it for troubleshooting. Also keep the relevant candidate or application identifier and the intended business action. A delivery identifier alone should not be your entire defense against repeating a downstream action.
For example, consider a proposed workflow that prepares a recruiter review when an application arrives. The desired result is a review item linked to that application. The desired result is not a new candidate record, an interview invitation or a hiring verdict. Write that boundary into the task specification.
Configure one event and prove the endpoint works
In Greenhouse Recruiting, webhook setup sits under Configure, Dev Center and Web hooks. The setup includes the event, endpoint URL, secret key and an error recipient email. Confirm that the person doing setup has permission to manage and configure webhooks.
Greenhouse sends a ping when a webhook is created. An unsuccessful ping leaves the saved configuration deactivated. Check the resulting enabled state rather than assuming that saving the form finished setup. If the endpoint fails during setup, fix the cause and explicitly re-enable the webhook.
Choose an error recipient who owns the integration. Greenhouse's support guidance says webhook failures do not produce an in-app notification. A mailbox that nobody reads is not useful operational coverage. Agree who checks alerts and how they find the affected application.
Verify the request before accepting candidate data
Greenhouse generates the Signature header using the secret key and request body. The receiver should compute the HMAC digest and compare it with the supplied signature. Keep the original body bytes available for this check. Do not verify a reconstructed JSON object after parsing and serializing it.
The developer documentation specifically notes escaped Unicode in signature generation. A body that looks equivalent after parsing can have different bytes. Include an escaped-character example in your receiver tests. Keep the secret in managed configuration, not in application logs or recruiter-facing error messages.
Use a queue and a business-action key
Keep slow model calls outside the incoming webhook request. A recommended pattern is to verify the request, validate the required fields, save the event and queue the task. The worker can then prepare the draft or review item without holding the delivery connection open.
Greenhouse documents retries for failed delivery. Its support page also allows retry settings to be configured. Check your account's settings and the current documentation rather than designing around an assumed fixed attempt count. Your integration should tolerate repeated input regardless of the configured count.
Define a business-action key from the application, workflow and action version. Before creating a review item, check whether that action has already completed or is in progress. A replay should return the existing outcome or safely resume incomplete work. It should not create another recruiter task by default.
| Step | Record to keep | Release check |
|---|---|---|
| Receive | Delivery ID and verification result | Invalid requests cannot create work |
| Queue | Application ID and task status | Saved work survives a worker restart |
| Prepare | Input version and proposed output | Missing evidence reaches review |
| Approve | Reviewer and approved action | Unapproved output cannot be sent |
| Replay | Prior action result | Completed work is not repeated |
Keep candidate data scoped to the task
Inspect the example payload for the exact event you plan to use. Greenhouse's documentation says exported custom fields can include public and private fields. Do not forward the entire payload to a model, analytics tool or shared chat simply because it arrived at your endpoint.
Build a field allowlist for each task. A review item might need the application identifier, job context and selected evidence. It may not need contact details, compensation fields or unrelated notes. Ask the recruiting owner to approve both the input fields and where the resulting draft is stored.
Plan candidate deletion and anonymization handling as separate paths. Greenhouse documents a deletion event that can include removed application IDs, and an anonymization event identifying affected fields. Use those signals to stop queued work and apply your approved data-handling policy to downstream copies. Do not assume deleting the ATS record automatically removes your copies.
Put approval at the action boundary
An AI worker can prepare a summary or draft while a recruiter reviews the evidence. Store the proposed output separately from an approved action. Before any send or write, check the current application state, the approved content and whether that action has already happened.
If a recruiter changes the record while the draft waits, mark the draft stale or require another review. Do not let an old event override a later human decision. Make a clear distinction between a task failing, a recruiter declining a suggestion and a candidate no longer being eligible for that workflow.
Mistakes to avoid before launch
- Checking the signature after changing the request body.
- Returning success before the event is safely saved.
- Running model calls inside the delivery request.
- Using retries without duplicate-safe business actions.
- Copying private fields into a general-purpose workspace.
- Treating an approved draft as approval for every later version.
Test a normal application, repeated delivery, an invalid signature, a worker restart and a missing required field. Then test a candidate deletion while work is queued. Have a recruiter inspect the resulting task and verify that no candidate-facing action happened without the required approval.
How Remqa builds recruiting event workflows
Remqa builds AI agents for recruiting teams around defined tasks, reviewed outputs and explicit action boundaries. Bring the event you want to use, the task it should start and the fields the worker may read.
Use the recruiting workflow map to choose the handoff worth automating. If the work also involves moving records between systems, start with the ATS migration scope. A useful first release is one that creates the right review task and can prove it did so without repeating an action.