A candidate applies in Ashby, but the AI research task never appears. Another candidate gets the same internal task twice after a delivery retry. Both problems start when an integration treats a webhook as a finished business action. The receiver needs to record what arrived. A separate worker needs to decide what should happen next. This guide covers that boundary for Ashby recruiting workflows.
Choose one event and one recruiting action
Start with a narrow job, such as preparing a recruiter review task after an application arrives. Write down the expected input, the proposed output and the person who owns exceptions. Do not connect every available event to a general agent and assume the agent will infer the correct workflow.
Ashby webhooks are configured under Admin, Integrations, Webhooks. Each configuration has an event type and a request URL. A secret token is optional in the product, but configure one for a production receiver. Ashby uses it to sign requests. Different event types can have different URLs, and one event can be sent to multiple configured URLs.
Keep those destinations intentional. A second receiver means another system receiving recruiting data. Record who owns it, what it stores and when its copies should be removed. The controls below are recommended integration design, separate from Ashby's documented webhook behavior.
Know what applicationSubmit does not cover
Ashby documents applicationSubmit for candidate applications and candidates manually added to Ashby. It does not fire for bulk imports or integration syncs. That matters when a recruiting team imports a database and expects the same AI preparation queue to appear automatically.
Maintain a coverage list. Record which entry paths produce your chosen event and which need a separate reconciliation job. Treat that reconciliation as its own workflow with its own approval rules. An imported historical profile should not accidentally receive the outreach intended for a new applicant.
| Situation | Documented behavior | Recommended control |
|---|---|---|
| Candidate applies or is manually added | applicationSubmit can trigger | Validate the application context before preparing work |
| Bulk import or integration sync | applicationSubmit does not trigger | Reconcile through a separately authorized path |
| Webhook configuration changes | A setup ping is sent | Test receipt and confirm the configuration is enabled |
| One event reaches several URLs | Multiple webhook destinations can be configured | Assign ownership and data rules to each receiver |
Verify the signature before parsing the body
Ashby sends the digest in the Ashby-Signature header when a secret token is configured. Its authentication guide uses HMAC SHA-256 and the original request body. Compute that digest before a JSON parser changes the representation. Recreating JSON from a parsed object can change whitespace or ordering and produce a different digest.
Use a secure digest comparison and keep the token outside application logs. Route the verified request to the expected customer configuration. Do not use the Ashby-Webhook user agent as authentication. Ashby explicitly describes that header as a routing convenience, not proof that a request came from Ashby.
Test valid and invalid signatures with controlled fixtures. Include a valid body whose whitespace changes, a missing header and an unexpected customer destination. The receiver should reject invalid requests without creating recruiting tasks or exposing candidate content in an error message.
Acknowledge durable receipt, not an unfinished AI run
The applicationSubmit reference describes a 200 response as successful receipt. Design the receiver to validate the envelope, save an event record and hand work to a queue. Return success only once the event has reached the durable boundary you chose. Avoid waiting for model generation, enrichment services or a recruiter decision inside the incoming request.
Give the stored record a processing status and a traceable application reference. Keep delivery status separate from action status. Received, queued, proposed, approved and completed are different facts. A dashboard that shows only successful HTTP requests will not reveal a worker that stopped before creating its proposed task.
Handle retries without repeating the business action
Ashby documents exponential backoff with a maximum of 10 attempts. Its first retry delays are 10, 30, 70 and 150 seconds. These are minimum delays, not precise delivery appointments. Do not build a recovery plan that assumes the next attempt arrives at an exact second.
The non-retryable response list is 401, 403, 404, 405 and 410. An expired secret, wrong route or removed endpoint can therefore need operator attention rather than another delivery attempt. Alert on these failures and inspect the configuration. Do not return success merely to hide an authentication problem.
Build duplicate protection around the intended action as well as delivery receipt. For example, track whether the application already has the specific preparation task for this workflow version. Make the check and claim durable so competing workers cannot both proceed. Define that action key in your own system rather than assuming every payload supplies a universal event identifier.
Recheck current state before any write
A worker can run after a recruiter has already moved the application or completed the task manually. Fetch the current permitted context before writing. Compare it with the conditions that justified the proposed action. If the application is no longer eligible, close the proposal with a reason instead of forcing the old action through.
For AI-written summaries, retain the evidence used and mark missing information explicitly. Bind approval to the actual proposed text and destination. A changed draft needs another review. Use the Ashby API permission checklist to separate the receiver's needs from the writer's permissions.
If an outbound write times out, treat its outcome as unknown until checked. Look for the intended result before retrying. A request log proves an attempt was made, not that the task was created exactly once.
Test failure paths with recruiting operations
- Confirm the setup ping is accepted and the webhook is enabled.
- Send a controlled valid event and trace it from receipt to proposed action.
- Repeat delivery and confirm the business action is not duplicated.
- Stop the worker after receipt and verify queued work remains recoverable.
- Import test records and confirm the reconciliation path handles the event gap.
- Change application state before execution and confirm the stale action is skipped.
- Revoke an approval and confirm the sender does not act.
Common mistakes include parsing before signature verification, logging full candidate payloads, confusing a setup ping with business work and assuming imports behave like applications. Assign a named operator to the failed-event queue and document how to replay a corrected event without replaying a completed action.
How Remqa builds Ashby webhook workflows
Remqa's recruiting AI work can cover the receiver, queue, review screen and controlled ATS handoff. The scope should include event coverage and failure tests, not just a successful demonstration. To discuss an integration, bring one event type, one proposed recruiting action and the exceptions your team currently handles by hand.