Receiving an application on your server
application.submitted on your webhook, its signature checked, then the application read through the API and matched to your job.
3 minute read
With delivery to your server switched on, every new application sends application.submitted to your webhook. The event carries ids, the job's words, your state and the terms, never the passport: your server reads the application through the API, a read that is logged and that the candidate sees. Set the webhook up first (Webhooks).
In the page, onSubmitted({ applicationId, state }) tells you it was sent. Nothing else reaches the browser unless delivery to the page is on too.
The event
{
"id": "01a2f3c4-6b7d-4e8f-9a0b-1c2d3e4f5a6b",
"type": "application.submitted",
"created_at": "2026-11-20T10:00:00Z",
"data": {
"organisation_id": "01a17b20-5d3c-4e8f-9a1b-2c3d4e5f6a7b",
"application": {
"id": "3f6b1a52-8c4d-4e9f-a1b2-c3d4e5f60718",
"state": "submitted",
"position_id": null,
"job": { "ref": "JOB-42", "title": "Backend engineer", "hiring_company": "Acme Robotics", "url": "https://jobs.hireline.example/job-42" },
"site_state": "st-9d1e5c7a2b",
"session_id": null,
"terms": { "scope_types": ["education", "employment"], "include_contact": true, "include_birth_date": false, "birth_date_reason": null, "requirements": null, "source": "general" },
"submitted_at": "2026-11-20T09:59:58Z",
"withdrawn_at": null,
"custom_data": { "board_job_id": 9912 }
},
"candidate_id": "7a1e2c3d-4b5f-4a6e-8d9c-0b1a2c3d4e5f"
}
}
site_state is your state; candidate_id is the id GET /v1/candidates/{id} takes. application.withdrawn has the same shape with state withdrawn and withdrawn_at set.
1. Check the signature
Over the raw body, before you parse it. Node, no dependencies:
// Check the certo-signature header of a webhook before you parse its body. Node, no dependencies.
import { createHmac, timingSafeEqual } from 'node:crypto'
import { Buffer } from 'node:buffer'
/**
* secret your signing secret, whsec_..., as certo showed it once
* header the request's certo-signature header: t=<unix seconds>,v1=<hex>
* rawBody the body exactly as it arrived, before any JSON parsing
* Answers true only for a signature made with your secret in the last five minutes.
*/
export function verifyCertoSignature(secret, header, rawBody, now = Math.floor(Date.now() / 1000)) {
if (typeof header !== 'string') return false
let t = null
const signatures = []
for (const part of header.split(',')) {
const [key, value = ''] = part.trim().split('=', 2)
if (key === 't' && /^\d{1,12}$/.test(value)) t = Number(value)
if (key === 'v1' && /^[0-9a-f]{64}$/.test(value)) signatures.push(Buffer.from(value, 'hex'))
}
if (t === null || signatures.length === 0 || Math.abs(now - t) > 300) return false
const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest()
return signatures.some((s) => timingSafeEqual(s, expected))
}
The same check in Python is in Webhooks.
2. Answer at once, work after
Answer any 2xx within ten seconds, then do the work from your own queue. If the certo-event-id header names an event you already handled, answer 200 and do nothing: an event can arrive twice.
app.post('/certo/webhook', express.raw({ type: 'application/json' }), (req, res) => {
if (!verifyCertoSignature(process.env.CERTO_WEBHOOK_SECRET, req.get('certo-signature'), req.body)) return res.status(400).end()
const event = JSON.parse(req.body.toString('utf8'))
res.status(200).end()
queue.add('certo-event', event)
})
3. Read the application
GET /v1/applications/{id} with a key that has candidates:read:
curl https://api.certo.bio/v1/applications/3f6b1a52-8c4d-4e9f-a1b2-c3d4e5f60718 \
-H "Authorization: Bearer $CERTO_API_KEY"
It answers { "application": ... }, the same object the page receives, described in the client side. The checklist (requirements) is in it when the key also has hiring:read. Each call is a read of the passport, logged, and the candidate sees that your organisation read it through its API: read when you need it, not on a timer.
| Code | When |
|---|---|
application.not_found | Not one of your applications |
grant.not_live | The candidate withdrew it: do not read further (After the application) |
4. Match it to your job
The application carries everything you sent: job.ref from the button or the session, state (on the event, site_state) for the visitor, session_id for an apply session, position_id for a position, and your custom_data. Match on the one your system already keys by.
A candidate who applies again for the same job updates the same application. That sends no second application.submitted; the page, if delivery to it is on, receives it again.
The list
GET /v1/applications (scope hiring:read) lists your applications, newest first, without passport content: the job, the terms, where each came from, open or withdrawn. Filter with ?position_id= and ?status=open|withdrawn, page with ?cursor= (Errors, limits and retries). Events are not saved up while your endpoint is off, so use the list to catch up after an outage.