Complete Developer Guide to Resume Screening Webhooks

Published on November 3, 2025 · Q&A format · A hands-on guide for developers implementing real-time resume screening notifications.

Q: What exactly are resume screening webhooks?

Think of webhooks as reverse APIs—instead of you constantly asking "Is the resume screened yet?", the screening service proactively pushes results to your endpoint when they're ready. You register an HTTPS URL, and boom, you get real-time JSON payloads whenever a candidate is scored, parsed, or rejected.

For resume screening specifically, webhooks typically fire on events like resume.parsed, candidate.scored, screening.completed, or match.found. Way cleaner than polling every 30 seconds and burning API quota.

Q: Why should I use webhooks instead of polling?

Three big wins: real-time updates (sub-second vs. minutes), zero wasted requests (no empty polls burning rate limits), and simpler code (no loop management or state tracking). If you're processing hundreds of resumes daily, webhooks can cut your API calls by 90%+ and deliver results instantly to recruiters.

The trade-off? You need a publicly accessible endpoint that can handle bursts, verify signatures, and return 200 fast. But once it's set up, it just works.

Q: What do I need to set up a webhook endpoint?

Four essentials:

• HTTPS endpoint: Must be publicly accessible with a valid SSL cert (HTTP won't cut it in 2025)
• Secret key: Provided by the screening service to generate and verify HMAC signatures
• Fast response: Return 200 OK within 5 seconds or the service assumes failure and retries
• Signature verification: Always validate the HMAC-SHA256 signature header to prevent spoofing

Most platforms also ping your endpoint with a test payload during registration—if you don't return 200, the webhook gets disabled automatically.

Q: How does HMAC signature verification actually work?

The screening service sends a Signature header like sha256 abc123def456.... Here's the drill:

• Grab the raw request body (before any parsing or middleware touches it)
• Compute HMAC-SHA256(secret_key, raw_body) and convert to hex
• Compare your computed hash to the signature using a constant-time function like crypto.timingSafeEqual() (Node.js) or hmac.compare_digest() (Python)
• If they match, proceed. If not, reject with 401

Gotcha: Some services escape Unicode in JSON before signing, so {"name":"José"} becomes {"name":"Jos\u00e9"}. Always check the docs for exact encoding rules.

Q: What does a typical payload look like?

Most resume screening webhooks follow this pattern:

{
  "event": "candidate.screening.completed",
  "timestamp": "2025-11-03T14:32:19Z",
  "webhook_id": "evt_abc123",
  "payload": {
    "candidate_id": "cand_xyz789",
    "job_id": "job_456",
    "score": 87,
    "match_status": "strong_match",
    "skills_matched": ["Python", "React", "PostgreSQL"],
    "experience_years": 5,
    "education_level": "Bachelor's",
    "screening_notes": "Strong technical background with relevant projects",
    "resume_url": "https://storage.example.com/resumes/xyz789.pdf"
  }
}
      

The event field tells you what happened, payload contains the data, and webhook_id helps with deduplication and replay protection.

Q: What event types should I handle?

Common events you'll see:

• resume.parsing.started – Processing began
• resume.parsing.completed – Text extracted, structured data ready
• candidate.screening.in_progress – AI scoring underway
• candidate.screening.completed – Final score and match status available
• candidate.rejected – Auto-rejection based on criteria
• error.parsing_failed – Corrupt file, unsupported format, etc.

Your endpoint should be idempotent and handle the same event multiple times gracefully (more on that below).

Q: How do I protect against replay attacks?

Two layers:

• Timestamp check: Reject events older than 5 minutes (abs(now - timestamp) > 300s)
• Event ID deduplication: Store processed webhook_ids in Redis/DB with TTL = 24h; skip if seen before

This stops attackers from re-sending old legitimate webhooks to trigger duplicate actions (like double-scoring candidates or sending duplicate emails).

Q: What if my endpoint is down? How do retries work?

Most services retry with exponential backoff. Typical pattern (from real ATS webhook docs):

• Attempt 1: Immediate
• Attempt 2: +1 minute
• Attempt 3: +15 minutes
• Attempt 4: +1 hour
• Attempt 5-7: Every 4-8 hours

After 7 failed attempts over ~15 hours, the event is usually dead-lettered and you'll need to poll a status endpoint or re-trigger manually. That's why fast 200 responses and monitoring matter.

Q: Should I process synchronously or queue the webhook?

Always queue it for anything non-trivial. Your webhook handler should:

• Verify signature (fast)
• Check replay protection (fast)
• Push to SQS/Pub/Sub/Redis queue
• Return 200 immediately

Then a separate worker consumes the queue and does the heavy lifting—updating your DB, calling ATS APIs, sending emails, etc. This keeps your endpoint response time under 200ms and avoids retry storms if downstream services are slow.

Q: What status codes should I return?

Simple rules:

• 200 OK: "Got it, don't retry" (even if you queued for later processing)
• 401 Unauthorized: Signature verification failed—logs this and doesn't retry (correct behavior)
• 500/503: Temporary failure—service will retry with backoff
• 4xx (except 401): Permanent failure—usually won't retry

Never return 200 if signature verification fails. Always return 200 if the event is valid, even if your downstream processing might fail later (handle that in the queue).

Q: How do I test webhooks locally during development?

Use tunneling tools to expose localhost:

• ngrok: ngrok http 3000 gives you a public HTTPS URL → https://abc123.ngrok.io
• localhost.run: ssh -R 80:localhost:3000 localhost.run (no install needed)
• Cloudflare Tunnel: cloudflared tunnel --url localhost:3000

Point the webhook registration to your tunnel URL. When testing, most services have a "Send test event" button that fires a sample payload immediately.

Q: What tools help debug webhook issues?

Three lifesavers:

• RequestBin / webhook.site: Inspects raw payloads and headers when you're not sure what's being sent
• Postman / Insomnia: Manually craft and send webhook payloads with custom signatures for edge case testing
• Structured logging: Log every incoming webhook with event, webhook_id, timestamp, and processing status. Elasticsearch + Kibana or Datadog makes debugging way easier

Pro tip: Log the raw request body and headers for the first 24 hours in production so you can replay failed events manually if needed.

Q: How do I handle partial failures (e.g., DB write succeeds but ATS update fails)?

This is where idempotency and transactional outbox patterns shine:

• Idempotent handlers: Use webhook_id or candidate_id + event as a dedup key. Store in DB before processing so re-delivery is safe
• Transactional outbox: Write webhook result + outgoing ATS API call to DB in one transaction. Separate worker polls outbox and retries ATS updates
• Dead-letter queue: After N retries, move to DLQ for manual inspection

This way, even if your ATS is down, you don't lose candidate data—you just retry the sync later.

Q: Can I customize which events trigger webhooks?

Most modern screening APIs let you subscribe to specific event types during registration. For example, if you only care about final scores, subscribe to candidate.screening.completed and skip parsing.started, parsing.in_progress, etc.

Some platforms also support filtering by job ID, location, or score threshold—so you only get webhooks for candidates scoring >70 on engineering roles, for instance.

Q: What's the difference between webhooks and websockets for this use case?

Webhooks are server-to-server HTTP POSTs—great for backend integrations. WebSockets are persistent connections—better for real-time browser UIs (like a live candidate dashboard).

For resume screening, you typically use webhooks to update your backend/ATS, then push updates to the browser via WebSockets or Server-Sent Events if you need live UI updates. Don't try to replace webhooks with WebSockets for server integrations—it's way more complex.

Q: How do I monitor webhook health in production?

Track these metrics:

• Success rate: % of webhooks returning 200 (target: >99.5%)
• P95 response time: How fast you return 200 (target: <200ms)
• Queue depth: Backlog of unprocessed events (alert if >1000)
• Retry count: How often the service had to retry (should be rare)
• Signature failures: Spikes indicate potential attacks or config issues

Set up alerts for response time >1s, success rate <95%, or any signature failures. Most webhook services also provide dashboards showing delivery attempts and failures.

Q: What are the most common mistakes developers make?

Top five:

• Not verifying signatures: Opens you to spoofed events and data corruption
• Synchronous processing: Slow DB writes or ATS calls timeout the webhook, triggering retries and duplicates
• No replay protection: Same event processed twice → duplicate candidate entries or scores
• Returning 200 on errors: Hides failures; the service thinks it succeeded but your data is wrong
• Using HTTP instead of HTTPS: Most services reject this outright; the few that don't are a security risk

Q: How do I rotate webhook secrets safely?

Best practice: Dual-key rotation

• Service adds a second secret and starts signing with both (sends two Signature headers or one concatenated)
• Your endpoint accepts webhooks if either signature is valid
• After 7 days (longer than max retry window), service drops the old key
• You update your code to only verify the new key

This ensures zero downtime and no lost events during rotation. Never just swap keys instantly—you'll reject in-flight retries from the old key.

Q: Do I need to implement webhook endpoints if I'm using a vendor ATS?

Depends. If your ATS (Greenhouse, Lever, Workday, etc.) already has a native integration with the screening service, you're golden—it's plug-and-play. But if you're building custom workflows (e.g., auto-scheduling top candidates, syncing to your own DB, triggering Slack notifications), you'll want your own webhook endpoint to intercept and route events.

Many teams run both: the ATS gets standard updates, and a custom endpoint handles specialized logic.

Q: What's a reference implementation that just works?

Simple Node.js example (Express):

const crypto = require('crypto');
const express = require('express');
const app = express();

app.post('/webhooks/resume-screening',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['signature'];
    const body = req.body.toString('utf8');

    // Verify HMAC
    const expected = 'sha256 ' + crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(body)
      .digest('hex');

    if (!crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    )) {
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(body);

    // Check replay (simplified; use Redis in production)
    if (seenEventIds.has(event.webhook_id)) {
      return res.status(200).send('Already processed');
    }

    // Queue for processing
    queue.push(event);
    seenEventIds.add(event.webhook_id);

    res.status(200).send('OK');
  }
);
      

For production, swap seenEventIds with Redis (TTL = 24h) and replace queue.push with SQS/Pub/Sub.

Q: Any final gotchas I should watch out for?

Yep:

• IP whitelisting: Some services send from dynamic IPs. Use signature verification, not IP allowlists
• Charset issues: Always handle UTF-8 (candidate names like "François" or "李明" must render correctly)
• Large payloads: If screening includes full resume text, payloads can be 50KB+. Ensure your server allows large request bodies
• Clock skew: If your server time is off by >5 minutes, timestamp validation fails. Use NTP

Related reading

• How to Integrate AI Resume Screening API with Your ATS
• Best Practices for Bulk Resume Processing via API
• Best Analytics for Optimizing Your Resume Screening Funnel

Join the conversation

• Developer & TA Forum – Webhook implementation tips
• r/recruiting – Real-time screening workflows
• Talent Acquisition & Recruitment Professionals