> ## Documentation Index
> Fetch the complete documentation index at: https://jobo.world/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Callbacks

> How Auto Apply requests typed answers from your systems over signed HTTPS callbacks, and how to verify the signature.

<Warning>
  Auto Apply is coming soon. This guide previews public API version `2026-07-21`;
  its portal controls, sandbox, and endpoints are not available to customers yet.
  Create is deployment-gated and currently returns HTTP `503` with problem code
  `auto_apply_coming_soon`. Do not run these examples against production.
</Warning>

## 1. Plan webhook configuration

At launch, **Auto Apply → Webhook settings** in the portal will accept a public
HTTPS callback URL. The generated account-level `whsec_...` value will be shown
once and must be stored securely.

Use **Send verification ping** at launch to validate connectivity and signature handling
before creating an application.

Webhook setup and secret rotation remain portal-only account controls. The
External API is limited to creating, listing, getting, and canceling
applications.

## 2. Verify signatures

Read the raw request body before JSON parsing. Calculate HMAC-SHA256 over:

```text theme={null}
X-Jobo-Webhook-Id + "." + X-Jobo-Webhook-Timestamp + "." + raw_body
```

Compare it in constant time with each `v1=...` value in
`X-Jobo-Webhook-Signature`. Reject timestamps more than five minutes from the
current time. During secret rotation, Jobo signs with both active secrets for
24 hours.

## 3. Return answers

For `application.fields_requested`, return a JSON command with a 2xx status:

```json theme={null}
{
  "action": "proceed",
  "answers": [
    { "field_id": "field_email", "value": "candidate@example.com" },
    { "field_id": "field_authorized", "value": true },
    { "field_id": "field_country", "value": "US" }
  ]
}
```

Every field marked `requires_answer: true` must appear exactly once. Use the
advertised option `value`, not its display label. To stop the application:

```json theme={null}
{ "action": "cancel" }
```

The callback deadline is an absolute 120 seconds. There is no deferred-answer
endpoint. Deduplicate callback work by `X-Jobo-Webhook-Id`; transport retries
reuse that value.

## 4. Preview a sandbox application request

At launch, copy a scenario URL from **Portal → Auto Apply → Sandbox**, then
use the request shape below. The command is illustrative and is not runnable today.

```bash theme={null}
export JOBO_SANDBOX_APPLY_URL="https://portal-provided-sandbox-url.example/scenario"

curl --request POST https://connect.jobo.world/api/auto-apply/applications \
  --header "X-Api-Key: $JOBO_API_KEY" \
  --header "Idempotency-Key: quickstart-education-1" \
  --header "Content-Type: application/json" \
  --data "{
    \"apply_url\": \"${JOBO_SANDBOX_APPLY_URL}\",
    \"sandbox\": true
  }"
```

Omitting `callback_url` will use the portal default. Sandbox availability and
quotas will be announced before launch.

## 5. Reconcile status

At launch, poll `GET /api/auto-apply/applications/{id}` after outages. It contains the
current status, failure taxonomy, per-step fields and accepted answers, and
terminal delivery attempts.

Create requires `Idempotency-Key`. Reusing the same key and body returns the
original application for 24 hours; changing the body returns
`409 idempotency_key_reuse`.