Integrations

Send Vakanssi's hiring events to Slack, Microsoft Teams, Zapier, Make, or your own service, with endpoints, the event catalog, automatic retries, a delivery log, and signature verification.

A webhook is a message your site sends to another service’s web address the moment something happens, with no polling and no copy-paste.

Vakanssi can send its hiring events to Slack, to Microsoft Teams, or to any webhook receiver: a Zapier Zap or a Make scenario (which can then update a spreadsheet, a CRM, or almost anything else), or a service your own team built. You choose where events go by adding endpoints on the Integrations tab.

Adding an endpoint

The endpoint form:

Each row in the Endpoints table has Edit, Send test, and Delete actions. To save and test in one step, use Save & send test on the form.

The events

Payloads are deliberately lean about personal data: the candidate appears as name and email only.

note.added carries who wrote the note and who it @mentions. With Collaboration Pro feature, requires a Vakanssi Pro license mentions on the note, the Slack and Teams line names both, for example “Avery mentioned Riley on Ava Johnson (Product Designer)”; a note with no mentions keeps the plain “Note added on…” wording.

The signed JSON payload always carries author and a mentions array (empty when there are none), plus a short note_excerpt of the note text.

Slack and Teams endpoints

A Slack or Teams endpoint posts one short, readable line to your channel per event, for example “New application: Ava Johnson applied for Product Designer”. You do not deal with any JSON.

To set one up, create an incoming webhook for the channel in Slack or Teams (each app has a feature for this that gives you a URL), then add a Vakanssi endpoint of the matching type and paste that URL. Vakanssi checks that the URL looks right for the type you picked and warns you if it does not.

How delivery works

• Applicants are shielded from a slow or down receiver. Events are queued during the request and sent only after the page has finished responding. On most hosts (anywhere PHP can hand the response back to the browser first) an applicant never waits on a delivery at all, and each delivery gets five seconds.
• On hosts that cannot hand the response back early (mod_php), each delivery is capped at two seconds instead, so a dead endpoint can delay the response only briefly. A delivery that misses that window is picked up by the automatic retry.
• Big batches are not dropped. Since v0.35.2, when one request queues more deliveries than it can send in time (a bulk move of hundreds of candidates, say), the rest wait in the log as “Queued to send” and the retry task delivers them within a few minutes.
• Automatic retries. A delivery that gets no response, a 429, or a 5xx error is tried up to four times in all, waiting 5 minutes, then 30 minutes, then 3 hours. A background task checks every 5 minutes; you do not have to do anything. Other errors, such as a 404, are not retried.
• Turning off an endpoint, or unticking one of its events, cancels its pending retries. The next retry, automatic or by hand, checks the endpoint again first: if it is now switched off or no longer subscribed to that event, Vakanssi abandons the send instead of firing it, and the log shows why.
• Send test and Resend. Send test on any endpoint delivers a sample payload immediately and reports the result. In the log, a delivery that failed or is waiting on a retry has a Resend link to try it again by hand right away.

The Recent deliveries log

Below the Endpoints table, Recent deliveries lists the latest delivery attempts, successes and failures alike, tests included. Each row shows when it happened, the event, the destination URL, how many tries it took, and the result: “OK” with the response code, “Failed” with the code and error, “Retry scheduled” or “Queued to send” with the time it goes out, or “Sending, no result yet”.

You can filter the log by endpoint. Entries are kept for 30 days, after which a daily task trims older rows.

Verifying webhook signatures

Every Webhook-type delivery (not Slack or Teams) is a JSON POST with these headers:

To confirm a request really came from your site, recompute the signature over the raw body (before any parsing) and compare in constant time:

$secret    = 'your-endpoint-signing-secret';
$body      = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_VAKANSSI_SIGNATURE'] ?? '';
$expected  = 'sha256=' . hash_hmac( 'sha256', $body, $secret );

if ( ! hash_equals( $expected, $signature ) ) {
    http_response_code( 403 );
    exit( 'Invalid signature' );
}

$payload = json_decode( $body, true );
// Trusted: handle the event.

Reject anything that fails the check. If you regenerate an endpoint’s secret, update the receiver at the same time.

The job title, stage, interview title and location, staff names, and note excerpt in the payload arrive as plain text, not HTML entities, so escape them yourself before putting them into HTML. The candidate’s name is the exception: it is sent as stored, since it comes from the public application form.