Outbound webhooks
Send signed InsightHire events, such as new applications, finished journeys and offer decisions, to an HTTPS endpoint your organization controls.
Outbound webhooks let another system hear about hiring events the moment they happen. When a candidate applies, finishes a journey, gets scored or answers an offer, InsightHire sends a signed message to a web address you choose.
This page is for whoever builds or runs the receiving system. If you just want hiring alerts in a chat channel, use Slack instead.
Who can do what
- Organization Admins create, edit, test, switch off and delete webhooks, and read the delivery log, under Settings → Integrations → Outbound webhooks.
- Everyone else can't open the Integrations page.
Create a webhook
- Open Settings → Integrations and choose Outbound webhooks under Advanced.
- Fill in:
- Name: so you recognize it later, up to 120 characters.
- Destination URL: must start with
https://. - Signing secret: choose Generate for a strong secret, or paste your own of at least 8 characters. Leave it empty and one is generated for you.
- Events: tick at least one.
- Description (optional).
- Enabled: on by default.
- Choose Create webhook.
- Copy the signing secret straight away. After this, only a masked version is shown.
To change the secret later, choose Edit, then Generate, then Save changes. Copy the new secret when it is shown. The old one stops working once you save.
Events
| Event | When it is sent |
|---|---|
application.created | A candidate applied |
application.status_updated | An application's status changed |
journey.started | A candidate started a journey |
journey.step.completed | A candidate finished a journey step |
journey.completed | A candidate finished a journey |
journey.failed | A journey ended because the candidate didn't pass a score gate |
score.updated | Scores or results are ready |
offer.accepted | A candidate accepted an offer |
offer.declined | A candidate declined an offer |
report.scheduled | A scheduled report was delivered, with a summary and a link to its data feed |
Subscribe only to the events your system uses. For report data feeds and their keys, see BI data feeds.
What each message looks like
Every message is an HTTPS POST with a JSON body in the same shape:
{
"id": "evt_abc123",
"event": "application.created",
"timestamp": "2026-08-03T20:00:00.000Z",
"organizationId": "org_123",
"data": { "...": "fields for this event" }
}Use id to ignore duplicates. The same event can arrive more than once if a delivery is retried.
Each request also carries these headers:
| Header | Value |
|---|---|
X-InsightHire-Timestamp | When it was signed, in Unix seconds |
X-InsightHire-Signature | t=<timestamp>,v1=<signature> |
X-InsightHire-Event | The event name |
X-InsightHire-Delivery-Id | The delivery attempt's ID |
X-InsightHire-Event-Id | The event's ID |
Check the signature
Always check the signature before trusting a message:
- Build the signed text: the timestamp, a full stop, then the raw request body, exactly as received.
- Compute an HMAC-SHA256 of that text with your signing secret, as hex.
- Compare it with the
v1value using a constant-time comparison. - Reject messages whose timestamp is more than 5 minutes old.
Example in Node.js:
const crypto = require('crypto');
function verifyInsightHireWebhook(rawBody, signatureHeader, secret, toleranceSec = 300) {
const parts = Object.fromEntries(
signatureHeader.split(',').map((p) => {
const [k, ...rest] = p.trim().split('=');
return [k, rest.join('=')];
})
);
const ts = Number(parts.t);
const v1 = parts.v1;
if (!Number.isFinite(ts) || !v1) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - ts) > toleranceSec) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${ts}.${rawBody}`, 'utf8')
.digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));
}Delivery and retries
- Reply with any
2xxstatus within 15 seconds to confirm you received it. - Anything else, or no reply, counts as a failure. InsightHire tries again a few times over the next couple of minutes, up to five attempts in total.
- InsightHire won't send to addresses on private or internal networks. Deliveries to those addresses fail straight away.
Test and monitor
- Choose Test on a webhook to send a signed test message. Its
datahas"test": true, so your system can tell it apart. - Recent deliveries lists each attempt with its event, status, number of attempts and time. Choose Retry on a failed delivery to send it again.
- Switch Enabled off to pause a webhook without deleting it.
Checklist for the receiving system
- Accept HTTPS
POSTrequests at the destination URL. - Check the signature before reading the body.
- Reply
2xxquickly, and do slow work afterwards. - Store each event
idand skip ones you've already handled.
Related
Public API
Read jobs, candidates and applications, add candidates, and move applications from your own tools with the InsightHire REST API and an API key.
Email sending and domains
How InsightHire sends email for your organization, how to connect your own SMTP or email provider, and how to verify your sending domain.
