Webhooks

Webhooks let your agent react to platform events instead of polling. When something notable happens — a new application, a stage change, a mutual match — JobMatch POSTs a signed event payload to your registered URL.

Events

Event	When it fires
application.created	A candidate’s application becomes active (after the undo window closes)
application.stage_changed	An application moves to a new pipeline stage; includes changed_by_agent if an agent triggered it
match.mutual	Both sides have chosen each other — candidate swiped right and company advanced the application

Payloads carry identifiers only — no candidate identity fields. Your agent must come back through the API to act on an event, which re-enforces anonymization on every response.

Setting up a webhook

In the company portal, go to Settings → Webhooks → Create webhook.

1. Enter your HTTPS endpoint URL
2. Select the events you want to receive
3. Copy the signing secret (whsec_…) — it is shown exactly once

Maximum 10 webhooks per company. HTTP URLs are not accepted in production.

Verifying signatures

Every delivery is signed with HMAC-SHA256. Verify before processing:

import hashlib, hmac, time

def verify_signature(payload: bytes, timestamp: str, signature_header: str, secret: str) -> bool:
    signed_payload = f"{timestamp}.{payload.decode()}"
    expected = "sha256=" + hmac.new(
        secret.encode(), signed_payload.encode(), hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(expected, signature_header):
        return False
    # Reject replays older than 5 minutes
    if abs(time.time() - int(timestamp)) > 300:
        return False
    return True

Headers on every delivery:

Header	Value
X-JobMatch-Event	Event name, e.g. application.stage_changed
X-JobMatch-Delivery	Unique delivery ID
X-JobMatch-Timestamp	Unix timestamp (seconds)
X-JobMatch-Signature	sha256=<hmac>

Delivery and retries

• Timeout: 10 seconds per attempt
• Retries: Linear backoff on failure, up to a platform-defined maximum
• Auto-disable: 20 consecutive failures disable the webhook. Re-enable it via the portal (Settings → Webhooks) — this resets the failure counter
• Best-effort: Webhook delivery failure never blocks the underlying business operation

Return any 2xx status to acknowledge delivery. Non-2xx responses are treated as failures and retried.

Managing webhooks

In the portal under Settings → Webhooks you can:

• View last delivery status and failure count per webhook
• Enable / disable without deleting
• Delete a webhook (stops all future deliveries)

Webhook management is restricted to COMPANY_ADMIN users.