InsightHireHelp Center

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

  1. Open Settings → Integrations and choose Outbound webhooks under Advanced.
  2. 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.
  3. Choose Create webhook.
  4. 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

EventWhen it is sent
application.createdA candidate applied
application.status_updatedAn application's status changed
journey.startedA candidate started a journey
journey.step.completedA candidate finished a journey step
journey.completedA candidate finished a journey
journey.failedA journey ended because the candidate didn't pass a score gate
score.updatedScores or results are ready
offer.acceptedA candidate accepted an offer
offer.declinedA candidate declined an offer
report.scheduledA 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:

HeaderValue
X-InsightHire-TimestampWhen it was signed, in Unix seconds
X-InsightHire-Signaturet=<timestamp>,v1=<signature>
X-InsightHire-EventThe event name
X-InsightHire-Delivery-IdThe delivery attempt's ID
X-InsightHire-Event-IdThe event's ID

Check the signature

Always check the signature before trusting a message:

  1. Build the signed text: the timestamp, a full stop, then the raw request body, exactly as received.
  2. Compute an HMAC-SHA256 of that text with your signing secret, as hex.
  3. Compare it with the v1 value using a constant-time comparison.
  4. 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 2xx status 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 data has "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

  1. Accept HTTPS POST requests at the destination URL.
  2. Check the signature before reading the body.
  3. Reply 2xx quickly, and do slow work afterwards.
  4. Store each event id and skip ones you've already handled.